> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Firecrawl MCP 工具和操作

> Firecrawl MCP 提供的工具、运行行为和错误处理。

<div id="available-tools">
  ## 可用工具
</div>

<div id="1-scrape-tool-firecrawl_scrape">
  ### 1. 抓取工具 (`firecrawl_scrape`)
</div>

使用高级选项从单个 URL 中抓取内容。

```json theme={null}
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown"],
    "onlyMainContent": true,
    "waitFor": 1000,
    "mobile": false,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "skipTlsVerification": false
  }
}
```

若要对个人身份信息进行脱敏，请在抓取工具的参数中添加 `redactPII`。

```json theme={null}
{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/contact",
    "formats": ["markdown"],
    "redactPII": true
  }
}
```

<div id="2-map-tool-firecrawl_map">
  ### 2. Map 工具 (`firecrawl_map`)
</div>

扫描网站，发现其中所有已编入索引的 URL。

```json theme={null}
{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com",
    "search": "blog",
    "sitemap": "include",
    "includeSubdomains": false,
    "limit": 100,
    "ignoreQueryParameters": true
  }
}
```

<div id="map-tool-options">
  #### Map 工具选项：
</div>

* `url`：要映射的网站基础 URL
* `search`：用于筛选 URL 的可选搜索词
* `sitemap`：控制 sitemap 的使用方式：“include”、“skip”或“only”
* `includeSubdomains`：映射时是否包含子域名
* `limit`：返回的最大 URL 数量
* `ignoreQueryParameters`：映射时是否忽略查询参数

**最适合：** 在决定抓取哪些内容前发现网站中的 URL；查找网站的特定部分。
**返回：** 网站中找到的 URL 数组。

<div id="3-search-tool-firecrawl_search">
  ### 3. 搜索工具 (`firecrawl_search`)
</div>

进行网页搜索，并可选择从搜索结果中提取内容。

```json theme={null}
{
  "name": "firecrawl_search",
  "arguments": {
    "query": "your search query",
    "limit": 5,
    "location": "United States",
    "tbs": "qdr:m",
    "scrapeOptions": {
      "formats": ["markdown"],
      "onlyMainContent": true
    }
  }
}
```

<div id="search-tool-options">
  #### Search Tool 选项：
</div>

* `query`：搜索查询字符串 (必填)
* `limit`：返回结果的最大数量
* `location`：搜索结果的地理位置
* `tbs`：基于时间的搜索筛选条件 (例如，`qdr:d` 表示过去一天，`qdr:w` 表示过去一周，`qdr:m` 表示过去一个月)
* `filter`：附加搜索筛选条件
* `sources`：要搜索的来源类型数组 (`web`、`images`、`news`)
* `scrapeOptions`：用于抓取搜索结果页面的选项
* `enterprise`：企业选项数组 (`default`、`anon`、`zdr`)

<div id="4-parse-tool-firecrawl_parse">
  ### 4. Parse Tool (`firecrawl_parse`)
</div>

将 PDF、DOCX、XLSX 或 HTML 等本地文件解析为干净、可供 LLM 使用的数据。

```json theme={null}
{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/report.pdf",
    "formats": ["markdown"]
  }
}
```

当你通过 `FIRECRAWL_API_URL` 在本地针对 Firecrawl API 实例运行 Firecrawl MCP 时，MCP 服务器可以直接读取 `filePath`，并将文件字节发送到 `/v2/parse`。

使用远程托管的 MCP 服务器时，托管服务器无法读取你机器上的文件。在这种情况下，`firecrawl_parse` 会采用两步交接流程，该流程同样适用于远程免密钥 URL：

1. 使用 `filePath` 调用 `firecrawl_parse`。该工具会返回一条预填充的上传命令，以及包含 `uploadRef` 的 `nextToolCall`。
2. 在能够读取该文件的机器上运行上传命令，然后使用返回的 `uploadRef` 再次调用 `firecrawl_parse`。

上传命令会将文件字节发送到一个短时有效的签名上传目标，其中不包含你的 Firecrawl API 密钥。

<div id="parse-tool-options">
  #### Parse Tool 选项：
</div>

* `filePath`：要解析的本地文件路径。首次调用时使用。
* `uploadRef`：首次托管 MCP 调用返回的引用。上传成功后，第二次调用时使用。
* `formats`：输出格式。默认值为 `markdown`。
* `parsers`：解析器控制选项，例如 PDF 解析选项。
* `contentType`：可选的文件 MIME 类型覆盖设置。
* `declaredSizeBytes`：可选的文件大小提示。文件大小上限为 50 MB。

**最适合：** 无法通过公开 URL 访问的本地或非公开文档。

**不建议用于：** 公开文档 URL。请改用 `firecrawl_scrape`；它会检测并解析 URL 中的文档。

<div id="5-crawl-tool-firecrawl_crawl">
  ### 5. 爬取工具 (`firecrawl_crawl`)
</div>

使用高级选项启动异步爬取。

```json theme={null}
{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}
```

<div id="6-check-crawl-status-firecrawl_check_crawl_status">
  ### 6. 查看爬取状态 (`firecrawl_check_crawl_status`)
</div>

查看爬取任务的状态。

```json theme={null}
{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**返回：** 爬取任务的状态和进度，以及 (如有) 结果。

<div id="7-extract-tool-firecrawl_extract">
  ### 7. 提取工具 (`firecrawl_extract`)
</div>

利用 LLM 从网页中提取结构化信息。支持云端 AI 和自托管 LLM。

```json theme={null}
{
  "name": "firecrawl_extract",
  "arguments": {
    "urls": ["https://example.com/page1", "https://example.com/page2"],
    "prompt": "Extract product information including name, price, and description",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["name", "price"]
    },
    "allowExternalLinks": false,
    "enableWebSearch": false,
    "includeSubdomains": false
  }
}
```

响应示例：

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": {
        "name": "Example Product",
        "price": 99.99,
        "description": "This is an example product description"
      }
    }
  ],
  "isError": false
}
```

<div id="extract-tool-options">
  #### Extract Tool 选项：
</div>

* `urls`: 用于提取信息的 URL 数组
* `prompt`: 用于 LLM 提取的自定义 prompt
* `schema`: 用于提取结构化数据的 JSON schema
* `allowExternalLinks`: 允许从外部链接中提取信息
* `enableWebSearch`: 启用网页搜索以获取额外上下文
* `includeSubdomains`: 提取时包含子域名

使用自托管实例时，提取将使用您配置的 LLM。云 API 则使用 Firecrawl 托管的 LLM 服务。

<div id="8-agent-tool-firecrawl_agent">
  ### 8. 代理工具 (`firecrawl_agent`)
</div>

自主网页调研代理，可根据你的查询自行浏览互联网、搜索信息、访问页面，并提取结构化数据。该操作以异步方式运行——会立即返回任务 ID，你可轮询 `firecrawl_agent_status` 检查任务何时完成并获取结果。

```json theme={null}
{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Find the top 5 AI startups founded in 2024 and their funding amounts",
    "schema": {
      "type": "object",
      "properties": {
        "startups": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "funding": { "type": "string" },
              "founded": { "type": "string" }
            }
          }
        }
      }
    }
  }
}
```

您还可以指定让代理重点关注的 URL：

```json theme={null}
{
  "name": "firecrawl_agent",
  "arguments": {
    "urls": ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    "prompt": "Compare the features and pricing information from these pages"
  }
}
```

<div id="agent-tool-options">
  #### 代理工具选项：
</div>

* `prompt`：所需数据的自然语言描述 (必填，最多 10,000 个字符)
* `urls`：可选的 URL 数组，用于让代理聚焦于特定页面
* `schema`：用于结构化输出的可选 JSON schema

**最适合：** 不清楚确切 URL 的复杂研究任务；多源数据收集；查找分散在网页各处的信息；从常规抓取无法处理的 JavaScript 密集型 SPA 中提取数据。

**返回：** 用于检查状态的任务 ID。使用 `firecrawl_agent_status` 轮询获取结果。

<div id="9-check-agent-status-firecrawl_agent_status">
  ### 9. 检查代理状态 (`firecrawl_agent_status`)
</div>

检查代理任务的状态，并在任务完成后获取结果。每隔 15～30 秒轮询一次，在判定请求失败前，至少持续轮询 2～3 分钟。

```json theme={null}
{
  "name": "firecrawl_agent_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

<div id="agent-status-options">
  #### 代理状态选项：
</div>

* `id`：`firecrawl_agent` 返回的代理任务 ID (必填)

**可能的状态：**

* `processing`：代理仍在调研中 -- 继续轮询
* `completed`：调研已完成 -- 响应中包含提取的数据
* `failed`：发生错误

\*\*返回：\*\*代理任务的状态、进度和结果 (如已完成) 。

<div id="10-interact-with-a-page-firecrawl_interact">
  ### 10. 与页面交互 (`firecrawl_interact`)
</div>

在实时浏览器会话中与页面交互：点击按钮、填写表单、提取动态内容，或继续深入导航。

可使用以下两种定位模式之一：

* 传入 `url`，即可在一次 MCP 调用中打开新页面并与其交互。
* 传入之前 `firecrawl_scrape` 调用返回的 `scrapeId`，以复用已加载的页面。

不要同时传入 `url` 和 `scrapeId`。请提供 `prompt` 或 `code` 其中之一。`scrapeOptions` 仅可在 `url` 模式下使用。

**URL 模式示例：**

```json theme={null}
{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com/products",
    "prompt": "Click on the first product and tell me its price"
  }
}
```

**复用抓取的示例：**

```json theme={null}
{
  "name": "firecrawl_interact",
  "arguments": {
    "scrapeId": "scrape-id-from-previous-scrape",
    "prompt": "Click the Sign In button"
  }
}
```

<div id="interact-tool-options">
  #### 交互工具选项：
</div>

* `url`：要交互的页面；系统会为您打开会话。使用此项或 `scrapeId`。
* `scrapeId`：此前调用 `firecrawl_scrape` 返回的抓取任务 ID。使用此项或 `url`。
* `prompt`：描述要执行操作的自然语言指令。提供 `prompt` 或 `code`。
* `code`：在浏览器会话中执行的代码。提供 `code` 或 `prompt`。
* `language`：`bash`、`python` 或 `node` (可选，默认值为 `node`，仅与 `code` 配合使用) 。
* `timeout`：执行超时时间 (秒) ，范围为 1–300 (可选，默认值为 30) 。
* `scrapeOptions`：仅在 `url` 模式下使用的可选抓取控制选项。

**最适合：** 在单个页面上执行多步骤工作流，例如搜索网站、点击搜索结果、填写表单，以及提取需要交互才能获取的数据。

**返回：** 包含输出和实时视图 URL 的交互结果。

<div id="11-stop-interact-session-firecrawl_interact_stop">
  ### 11. 停止交互会话 (`firecrawl_interact_stop`)
</div>

停止已抓取页面的交互会话。完成交互后调用此工具以释放资源。

```json theme={null}
{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-from-previous-scrape"
  }
}
```

<div id="interact-stop-options">
  #### 交互停止选项：
</div>

* `scrapeId`：要停止的会话对应的抓取 ID (必填)

\*\*返回：\*\*确认会话已停止。

<div id="logging-system">
  ## 日志系统
</div>

服务器提供全面的日志记录，包括：

* 操作状态和进度
* 性能指标
* 额度使用情况监控
* 限流跟踪
* 错误情况

日志示例：

```
[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[INFO] Starting crawl for URL: https://example.com
[WARNING] Credit usage has reached warning threshold
[ERROR] Rate limit exceeded, retrying in 2s...
```

<div id="error-handling">
  ## 错误处理
</div>

服务器提供完善的错误处理机制：

* 自动重试瞬时错误
* 通过退避策略处理限流
* 提供详细的错误信息
* 额度使用警告
* 网络容错能力

错误响应示例：

```json theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded. Retrying in 2 seconds..."
    }
  ],
  "isError": true
}
```