Firecrawl MCP Server

Firecrawl MCP Server

一个模型上下文协议（MCP）服务，可将面向 AI Agent 的上下文 API Firecrawl 引入兼容 MCP 的客户端：搜索、抓取并与实时网络交互，获取整洁的 Markdown 或结构化数据。

特别感谢 @vrknetha 和 @knacklabs 提供初始实现！

功能

• 搜索网络，可选择获取每条结果的完整页面内容
• 搜索开发者来源索引（GitHub issues、已合并的拉取请求、README 和文档）、美国政府来源以及科学论文（PubMed、bioRxiv、medRxiv、arXiv）
• 将任意 URL 抓取为整洁的 Markdown 或结构化 JSON
• 解析 PDF 和文档
• 抓取网站的多个页面以获取内容，或映射网站以发现其 URL
• 在真实浏览器中与页面交互：点击、输入、填写表单并浏览动态页面
• 执行 Agent 任务，开展多来源研究并返回结构化数据
• 监控页面并在内容变化时收到通知
• 查看当前和历史 Firecrawl 点数用量
• 自动重试和速率限制
• 支持云端和可自托管
• 支持 SSE

欢迎在 MCP.so 的 Playground 中试用我们的 MCP Server，或在 Klavis AI 上体验。

何时使用此服务

• 已知 URL，且希望获取其 Markdown 内容或符合所提供架构的 JSON 时，请使用 firecrawl_scrape。
• 需要发现网站上的 URL，但不获取其内容时，请使用 firecrawl_map。
• 需要获取网站下多个页面的内容时，请使用 firecrawl_crawl；设置 limit、includePaths/excludePaths 或 maxDiscoveryDepth 来限制范围。
• 从查询而非 URL 开始搜索，并需要按相关性排序的网络结果时，请使用 firecrawl_search。结果包含摘要；可对所需 URL 使用 firecrawl_scrape 获取完整页面。scrapeOptions 会在同一次调用中获取每条结果的页面，并按抓取计费，因此仅在需要少数几条结果的全文时使用（仅搜索端点不会获取内容）。
• 页面需要先点击、输入或导航，然后才能读取时，请使用 firecrawl_interact：为新页面传入 url，或传入 scrapeId 以继续操作已抓取的页面。
• 需要定期检查同一页面，并获取差异和变更提醒，而非只抓取一次时，请使用 firecrawl_monitor_* 工具。
• 需要查看剩余点数，或按月、按日了解点数的使用情况（可选择按端点或 API 密钥细分）时，请使用 firecrawl_credit_usage。
• 如果需要在自己的多个步骤中保持浏览器会话开启，并自行控制重试和终止逻辑，请考虑使用其他方案：每次 firecrawl_interact 调用都会运行一个 prompt 或 code 回合直至完成，然后返回控制权。会话可通过 scrapeId 在多次调用间保持，并通过 firecrawl_interact_stop 结束，但客户端无法在单次调用中逐步交互式地驱动会话。

默认设置下，完整配置文件注册时（包括反馈工具，且未以本地免密钥模式运行），此服务会列出 27 个工具。设置 FIRECRAWL_NO_SEARCH_FEEDBACK=1 和/或 FIRECRAWL_NO_ENDPOINT_FEEDBACK=1 会移除对应的反馈工具并减少此数量，本地免密钥启动也会减少工具数量。对于有工具槽位限制的客户端：托管免密钥端点（https://mcp.firecrawl.dev/v2/mcp，无需 API 密钥）仅提供 3 个工具（firecrawl_scrape、firecrawl_search、firecrawl_parse）；专用的仅搜索端点（https://mcp.firecrawl.dev/v2/mcp-search）提供固定的 9 个工具（搜索、开发者、政府和研究搜索，以及 Alexandria 目录查询和执行）。

安装

托管 MCP（免密免费套餐）

无需设置即可连接到托管的远程服务：

https://mcp.firecrawl.dev/v2/mcp

在免密免费套餐中，scrape、search 和 parse 无需 API 密钥即可使用（但有速率限制）。crawl、map 和 agent 等其他工具仍需要密钥。

只要用户可以注册，就优先使用 OAuth 或 API 密钥。这样可以解锁完整的工具集并提高使用限额。

如需交互式连接账户，请将 MCP 客户端配置为使用此服务 URL。这是一个 MCP 端点，不是浏览器页面；请使用客户端的账户连接流程，重新连接时不要添加第二个 Firecrawl 服务条目：

https://mcp.firecrawl.dev/v2/mcp-oauth

如需使用 API 密钥连接（例如，无人值守的集成），请将服务 URL 保持为：

https://mcp.firecrawl.dev/v2/mcp

然后在客户端的安全标头或密钥设置中配置：

Authorization: Bearer <FIRECRAWL_API_KEY>

切勿将 API 密钥放入服务 URL 或 Agent 聊天中。请直接在客户端或密钥管理器中配置。有关特定客户端的说明，请参阅托管 MCP 设置指南和 Agent 入门指南。

为集成命名

通过 HTTP 连接的集成可以使用 X-Firecrawl-Origin 标头为自身命名，例如 X-Firecrawl-Origin: my-agent。服务会将其作为请求来源 mcp-my-agent@<server version> 报告给 Firecrawl，替代原本要报告的客户端名称或 User-Agent。请使用字母、数字和连字符：其他字符的连续组合会转换为一个连字符，开头和结尾的连字符会被删除，名称最长为 48 个字符。这不会影响工具结果；只有发送到 Firecrawl API 的来源（以及传递给嵌入器 beforeKeylessRequest 的来源）会发生变化。

仅搜索端点

托管服务还提供固定范围的搜索接口：

https://mcp.firecrawl.dev/v2/mcp-search

它提供固定的九个工具：firecrawl_search、firecrawl_developer_search、firecrawl_gov_search、四个 firecrawl_research_* 工具，以及两个 Alexandria 工具 firecrawl_find_tools 和 firecrawl_scrape。其 firecrawl_search 不会获取网页内容。

使用 npx 运行

env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

手动安装

npm install -g firecrawl-mcp

在 Cursor 上运行

配置 Cursor 🖥️ 注意：需要 Cursor 0.45.6+ 版本 如需获取最新的配置说明，请参阅 Cursor 官方文档中有关配置 MCP 服务的内容： Cursor MCP 服务配置指南

在 Cursor v0.48.6 中配置 Firecrawl MCP

1. 打开 Cursor 设置
2. 前往 Features > MCP Servers
3. 点击“+ Add new global MCP server”
4. 输入以下代码：

   {
     "mcpServers": {
       "firecrawl-mcp": {
         "command": "npx",
         "args": ["-y", "firecrawl-mcp"],
         "env": {
           "FIRECRAWL_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }
   

在 Cursor v0.45.6 中配置 Firecrawl MCP

1. 打开 Cursor 设置
2. 前往 Features > MCP Servers
3. 点击“+ Add New MCP Server”
4. 输入以下内容：
   • 名称：“firecrawl-mcp”（或你偏好的名称）
   • 类型：“command”
   • 命令：env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

如果你使用 Windows 并遇到问题，请尝试 cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp"

将 your-api-key 替换为你的 Firecrawl API 密钥。如果你还没有密钥，可以创建账户并从 https://www.firecrawl.dev/app/api-keys 获取。

添加后，刷新 MCP 服务列表即可看到新工具。Composer Agent 会在适当时自动使用 Firecrawl MCP；你也可以描述需要从网上获取什么内容，明确要求使用它。按 Command+L（Mac）打开 Composer，在提交按钮旁选择“Agent”，然后输入查询。

在 Windsurf 上运行

将以下内容添加到你的 ./codeium/windsurf/model_config.json：

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

使用 Streamable HTTP 本地模式运行

要在本地使用 Streamable HTTP 运行服务，而不是使用默认的 stdio 传输：

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp

使用此 URL：http://localhost:3000/mcp

在此模式下，服务只会响应目标为 localhost、127.0.0.1 或 [::1]（任意端口均可）的请求，以及目标为 HOST 中地址的请求（当其值不是 0.0.0.0 或 :: 时）。如果请求的 Host 标头指定了其他主机，或 Origin 标头指定了其他站点，服务会返回 403；CORS 标头会回显允许的来源，而不是 *。无论主机是什么，对 /health 的 GET 和 HEAD 请求都会得到响应，因此健康检查仍可正常工作。对于每个拒绝的请求，服务都会记录一行日志，指出 FIRECRAWL_MCP_ALLOWED_HOSTS。这样可以阻止你访问的网页通过 DNS 重绑定或跨来源请求调用本地服务，并使用其 FIRECRAWL_API_KEY。

要通过其他名称或地址访问服务（例如反向代理后的主机名或 LAN IP），请在 FIRECRAWL_MCP_ALLOWED_HOSTS 中列出该名称或地址（以逗号分隔；端口会被忽略）。同一列表也决定了哪些浏览器来源可以调用服务。运行在同一台机器上的反向代理可以保留默认绑定地址：

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  FIRECRAWL_MCP_ALLOWED_HOSTS=mcp.home.lan npx -y firecrawl-mcp

其他机器上的客户端还需要服务监听非回环地址，因此也要设置 HOST。这样，任何可以访问该端口的客户端都会使用服务的 FIRECRAWL_API_KEY，因此只有在可信网络中才这样配置：

env HTTP_STREAMABLE_SERVER=true FIRECRAWL_API_KEY=fc-YOUR_API_KEY HOST=0.0.0.0 \
  FIRECRAWL_MCP_ALLOWED_HOSTS=192.168.1.20 npx -y firecrawl-mcp

FIRECRAWL_MCP_ALLOWED_HOSTS=* 会关闭此检查并恢复通配符 CORS 标头。只有当前置组件会自行检查主机和来源时，才这样设置。

使用 Docker 运行

ghcr.io/firecrawl/firecrawl-mcp-server 镜像运行的服务与 npx -y firecrawl-mcp 相同。main 上的每个构建都会标记为 latest、v<package version> 和 sha-<commit sha>。v<package version> 会指向该版本的最新构建，因此需要固定镜像时，请锁定 sha-<commit sha>（或摘要）。

stdio（默认方式），适用于以命令形式启动服务的 MCP 客户端：

docker run -i --rm -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY ghcr.io/firecrawl/firecrawl-mcp-server:latest

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FIRECRAWL_API_KEY", "ghcr.io/firecrawl/firecrawl-mcp-server:latest"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Streamable HTTP，服务地址为 http://localhost:3000/mcp：

docker run --rm -p 127.0.0.1:3000:3000 \
  -e HTTP_STREAMABLE_SERVER=true \
  -e FIRECRAWL_API_KEY=fc-YOUR_API_KEY \
  ghcr.io/firecrawl/firecrawl-mcp-server:latest

镜像会设置 HOST=0.0.0.0 和 PORT=3000；要在其他端口监听，请覆盖 PORT（以及 -p 映射）。对于未提供自身凭据的请求，服务会使用容器的 FIRECRAWL_API_KEY，因此示例只会将端口发布到 127.0.0.1；除非客户端必须提供自己的密钥，否则不要将其暴露到更广泛的网络中。设置 FIRECRAWL_API_URL 可使用可自托管的 Firecrawl API。容器以非特权 node 用户运行。服务只会接受 Host 和 Origin 标头中的 localhost、127.0.0.1 和 [::1]，因此 -p 127.0.0.1:3000:3000 映射可以直接使用；要通过其他名称访问，请设置 -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host>（参见 Streamable HTTP 本地模式）。

在 VS Code 中运行

如需一键安装，请点击下面的任一安装按钮……

如需手动安装，请将以下 JSON 代码块添加到 VS Code 的“用户设置（JSON）”文件中。按 Ctrl + Shift + P 并输入 Preferences: Open User Settings (JSON) 即可打开该文件。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Firecrawl API Key",
        "password": true
      }
    ],
    "servers": {
      "firecrawl": {
        "command": "npx",
        "args": ["-y", "firecrawl-mcp"],
        "env": {
          "FIRECRAWL_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

你也可以选择将其添加到工作区中名为 .vscode/mcp.json 的文件里，以便与他人共享配置：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Firecrawl API Key",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:apiKey}"
      }
    }
  }
}

配置

环境变量

云 API 必需项

• FIRECRAWL_API_KEY：你的 Firecrawl API 密钥
  • 使用云 API（默认）时必需
  • 使用带有 FIRECRAWL_API_URL 的自托管实例时可选
• FIRECRAWL_API_URL（可选）：自托管实例的自定义 API 端点
  • 示例：https://firecrawl.your-domain.com
  • 如果未提供，则使用云 API（需要 API 密钥）
• FIRECRAWL_INTEGRATION（可选）：用于启动此服务的应用（例如编辑器扩展）的集成标签
  • 作为 integration 字段随 scrape、batch scrape、crawl、map、search、extract、agent、parse、interact 和 feedback 请求发送
  • 使用以下划线 _ 开头的值，例如 _zed

本地 HTTP 模式

• FIRECRAWL_MCP_ALLOWED_HOSTS（可选）：启用 HTTP_STREAMABLE_SERVER=true 或 SSE_LOCAL=true 时，服务响应的额外主机名或地址，以逗号分隔
  • 始终允许 localhost、127.0.0.1、[::1] 和非通配符 HOST；端口会被忽略
  • Host 或 Origin 标头中包含其他主机名的请求会收到 403，但对 /health 的 GET 和 HEAD 请求除外
  • * 会关闭检查；与 CLOUD_SERVICE=true 搭配时不使用此检查，因为该模式会响应所有主机

MCP OAuth（Bearer 访问令牌）

Firecrawl 通过 firecrawl.dev 上的授权服务器颁发 OAuth 访问令牌（fco_…）。此 MCP 服务会将其解析出的凭据转发给 Firecrawl API，并作为 Authorization: Bearer … 发送。

• HTTP 流传输（CLOUD_SERVICE=true、HTTP_STREAMABLE_SERVER=true 或 SSE_LOCAL=true）：客户端应在 MCP 请求中发送 Authorization: Bearer <fco_access_token>。同时存在 OAuth Bearer 令牌与 x-firecrawl-api-key / x-api-key 时，优先使用 OAuth Bearer 令牌。
• **stdio：**静态访问令牌请使用 FIRECRAWL_OAUTH_TOKEN；API 密钥则可继续使用 FIRECRAWL_API_KEY。

仅使用访问令牌（fco_…）。刷新令牌（fcr_…）必须在令牌端点进行交换，不得传递给 scrape/search API。

CLOUD_SERVICE=true

CLOUD_SERVICE=true 会通过 PORT（默认为 3000，绑定到 0.0.0.0）上的可流式传输 HTTP 提供工具，并采用更严格的默认设置：每个请求都必须携带凭证（API 密钥或 OAuth 访问令牌）；scrape 为只读（请参阅下方的 scrape 工具）；且 firecrawl_parse 仅接受上传内容。

FASTMCP_ENDPOINT 用于选择工具接口：完整工具集对应 /v2/mcp（默认值），账户接口对应 /v2/mcp-oauth，仅搜索工具对应 /v2/mcp-search（还需要设置 FIRECRAWL_MCP_SEARCH_OAUTH_ONLY=true）。使用完整接口时，还会在端口 3001 上启动仅搜索实例；设置 FIRECRAWL_MCP_SEARCH_ENABLED=false 可将其关闭。

配置示例

用于云 API：

export FIRECRAWL_API_KEY=your-api-key

用于可自托管实例：

# Required for self-hosted
export FIRECRAWL_API_URL=https://firecrawl.your-domain.com

# Optional authentication for self-hosted
export FIRECRAWL_API_KEY=your-api-key  # If your instance requires auth

与 Claude Desktop 搭配使用

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-server-firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

如何选择工具

根据以下指南为任务选择合适的工具：

• 如果你知道要访问的确切 URL： 使用 scrape（结构化数据请使用 JSON 格式）
• 如果你有多个已知 URL： 对每个 URL 调用 scrape。如果你明确需要一次批量 API 操作，请在 MCP 之外使用 Firecrawl API 批量端点。
• 如果你需要发现某个网站上的 URL： 使用 map
• 如果你想搜索网络信息： 使用 search
• 如果你有编程问题（库、API 契约、错误消息、已知 bug）：使用 developer search
• 如果你有法律或监管问题（法律、法规、法典、法院意见或其他美国政府出版物）：使用 Firecrawl Government Index
• 如果你需要科学论文（生物医学、生命科学、临床或 arXiv 文献）：使用 research tools，它们会搜索论文摘要和全文。使用 categories: ["research"] 的 search 则不同：它是在普通网络搜索结果中应用的网站筛选条件。
• 如果你需要返回结构化数据的多来源研究、不知道 URL，或答案涉及多个网站（某个实体及其字段、列表、数据集）：使用 agent
• 如果你想分析整个网站或某个版块： 使用 crawl（请设置限制！）
• 如果你需要交互式浏览器自动化（点击、输入、导航）：对于新页面，请使用带 URL 的 interact；如果你已抓取页面或需要更精细地控制抓取，请使用 scrape + interact
• 如果你需要从已编目的提供商（Alexandria）获取数据： 使用 sources: ["alexandria"] 进行搜索，使用 find_tools 检查选定的契约，然后使用 scrape alexandria 执行

快速参考表

工具	最适合的场景	返回内容
scrape	单个页面内容	JSON（首选）或 Markdown
interact	与 URL 或抓取的页面交互	执行结果 + URL 模式下的 scrapeId
map	发现网站上的 URL	URL[]
crawl	多页面提取（有限制）	内部轮询后的最终爬取状态/数据
parse	文件和托管上传引用	Markdown、JSON 或文档输出
search	搜索网络信息	results[]
find_tools	浏览 Alexandria 目录并查找 URL	提供方、工具契约和 nextTool 导航
developer	针对开发者来源的编程问题	包含段落的 results[]
gov	美国主要法律和监管材料	包含摘要的 results[]
agent	多来源研究、未知网站或多个网站	JSON（结构化数据）
monitor	定期检查页面	监控/检查元数据和差异
research	论文和 GitHub 仓库研究	研究结果和仓库匹配项

格式选择指南

使用 scrape 时，请选择合适的格式：

• JSON 格式（大多数情况下推荐）： 当你需要从页面中提取特定数据时使用。根据需要提取的内容定义架构。这样可以缩小响应，并避免上下文窗口溢出。
• Markdown 格式（谨慎使用）： 仅当你确实需要完整页面内容时使用，例如阅读整篇文章以进行摘要，或分析页面结构。

可用工具

1. 抓取工具（firecrawl_scrape）

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

最适合：

• 提取单个页面的内容，且你确切知道哪个页面包含所需信息。

不推荐用于：

• 提取多个页面的内容（对于已知 URL，可重复调用抓取；也可先用 map 发现 URL，再抓取；或使用 crawl 获取完整页面内容）
• 不确定哪个页面包含所需信息时（使用搜索）

常见错误：

• 在一次抓取调用中传入 URL 列表。在 MCP 中，每个 URL 调用一次抓取。如果确实需要一次批量 API 操作，请在 MCP 之外使用 Firecrawl API 批量端点。
• 默认使用 markdown 格式（使用 JSON 格式，仅提取所需内容）。

选择合适的格式：

• JSON 格式（首选）： 对于大多数用例，使用带有架构的 JSON 格式，仅提取所需的特定数据。这样可以让响应重点突出，并避免上下文窗口溢出。
• Markdown 格式： 仅当任务确实需要完整页面内容时使用（例如，总结整篇文章、分析页面结构）。

提示词示例：

“从 https://example.com/product 获取产品详情。”

用法示例（JSON 格式 - 首选）：

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": [
      {
        "type": "json",
        "prompt": "Extract the product information",
        "schema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "number" },
            "description": { "type": "string" }
          },
          "required": ["name", "price"]
        }
      }
    ]
  }
}

用法示例（markdown 格式 - 需要完整内容时）：

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/article",
    "formats": ["markdown"],
    "onlyMainContent": true
  }
}

用法示例（branding 格式 - 提取品牌形象）：

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["branding"]
  }
}

Branding 格式： 提取完整的品牌形象（颜色、字体、排版、间距、徽标、UI 组件），用于设计分析或风格复刻。 隐私： 设置 redactPII: true，即可返回已隐去个人身份信息的内容。 使用 CLOUD_SERVICE=true 时： scrape 为只读操作。它不接受浏览器 actions，也无法接受提供商条款。指定名称的 profile 会加载已保存的浏览器状态，但不会保存更改；完整端点中的 firecrawl_search 对 scrapeOptions.profile 的处理方式相同。若要将浏览器状态保存到 profile，请使用 firecrawl_interact 打开页面（见下文）。组织管理员可在控制面板中接受条款。

返回：

• 按指定格式返回 JSON 结构化数据、markdown、品牌资料或其他内容。

2. 映射工具（firecrawl_map）

映射网站，以发现该网站上已编入索引的所有 URL。

最适合：

• 在决定抓取哪些内容之前，发现网站上的 URL
• 查找网站的特定版块

不推荐用于：

• 已知道需要哪个特定 URL 时（使用 scrape）
• 需要获取页面内容时（映射后使用 scrape）

常见错误：

• 使用 crawl 而不是 map 来发现 URL

提示词示例：

“列出 example.com 上的所有 URL。”

用法示例：

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com"
  }
}

返回：

• 网站上找到的 URL 数组

3. 搜索工具（firecrawl_search）

搜索 Web，并可选择从搜索结果中提取内容。

最适用于：

• 在多个网站中查找特定信息，但不知道哪些网站包含相关信息。
• 需要获取与查询最相关的内容时。

不建议用于：

• 已经知道要抓取哪个网站时（请使用 scrape）。
• 需要全面覆盖单个网站时（请使用 map 或 crawl）。

常见错误：

• 对开放式问题使用 crawl 或 map（请改用 search）。

用法示例：

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "remote work stipend policies at tech companies",
    "highlights": true,
    "limit": 5,
    "lang": "en",
    "country": "us"
  }
}

如需在同一次调用中获取少数几个结果的全文，请添加 "scrapeOptions": { "formats": ["markdown"], "onlyMainContent": true }。每个抓取的结果都会按一次 scrape 计费，因此对于大多数问题，请使用摘要，并仅对需要的 URL 调用 firecrawl_scrape。

将 highlights 设为 true，可请求与查询相关的重点内容；设为 false，则保留原始搜索摘要。不设置该选项时，将使用 API 的默认行为。

添加 "sources": ["alexandria"]，即可在 data.tools 中进行语义工具发现，也可将其与 web/news/images 混合使用。此时必须提供查询。请使用 firecrawl_find_tools 进行上下文查找和渐进式披露；参见 Alexandria Tools。

有关科学论文，请参见 Research Tools：这些工具会搜索论文摘要和全文，而此处的 categories: ["research"] 则会将普通 Web 搜索结果筛选为与研究相关的网站。

返回内容：

• 按来源分组的搜索结果（data.web、data.images、data.news），可选包含抓取的内容，并附有 id 字段。每个结果都带有 source 和从 1 开始的 position；该编号在各自分组内独立计算。请将这两个值直接复制到 firecrawl_search_feedback 的 valuableResults 中，不要通过数组元素计数。使用结果后，将其 id 传递给 firecrawl_search_feedback，即可退还 1 个积分（搜索需 2 个积分）并提升搜索质量。

提示词示例：

“比较各科技公司针对远程办公补贴的政策。”

3b. 搜索反馈工具（firecrawl_search_feedback）

针对之前的 firecrawl_search 结果发送结构化反馈。每个搜索 id 的首次反馈会退还 1 个积分，并提升 Firecrawl 的搜索质量。每个搜索 id 仅处理一次。

请在每次实际使用搜索结果后调用此工具（即使搜索结果没有帮助也应调用）。包含 missingContent 的不佳或不完整反馈同样有价值。

**选择退出：**启动 MCP 服务时，在环境中设置 FIRECRAWL_NO_SEARCH_FEEDBACK=1（或 FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1）。这样不会注册 firecrawl_search_feedback 工具，Agent 也就无法调用它。团队管理员也可以在服务端禁用反馈；此时工具仍会注册，但始终返回 feedbackErrorCode: "TEAM_OPTED_OUT"。

最重要的字段：missingContent。这是一个数组，包含 Agent 预期找到但未能找到的具体内容。每个缺失主题单独列为一项；这些内容会在团队间汇总，帮助我们确定接下来要索引的内容。若要提供有用的结果，请在 valuableResults 中填写每个结果上标注的 source/position 对。结果按组分组，且每组都独立从 1 开始编号，因此两项都必须填写。请列出所有有用的结果（未列出的结果会被视为无用）；仅将未包含在返回结果中的有用 URL 填入 valuableSources。

**每日退款上限（按团队和 UTC 日期计算，默认 100 个积分）。**当团队的 creditsRefundedToday 达到 dailyRefundCap 后，后续提交仍会记录反馈，但不再退还积分。响应中会设置 dailyCapReached: true。看到此标志后，Agent 应在当天剩余的 UTC 时间内停止调用此工具。

用法示例：

{
  "name": "firecrawl_search_feedback",
  "arguments": {
    "searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "good",
    "valuableResults": [
      { "source": "web", "position": 1 },
      { "source": "web", "position": 3 },
      { "source": "news", "position": 2, "reason": "Broke the pricing change." }
    ],
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/pricing",
        "reason": "Not in the results; found via a result's pricing link. Answered the question."
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      },
      { "topic": "Per-team rate limits" }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
  }
}

返回内容：

• { success, feedbackId, creditsRefunded, alreadySubmitted? } JSON。

3c. 通用反馈工具（firecrawl_feedback）

通过 /v2/feedback 为已完成的 v2 端点任务发送结构化反馈。 可用于针对 scrape、parse、map 或 search 任务的端点级反馈。若专门针对搜索结果质量，请优先使用 firecrawl_search_feedback，因为它包含搜索专属指导。

反馈内容应简洁：使用问题代码、标签、简短备注、URL、页码 和小型元数据对象。请勿包含原始抓取或解析输出。

选择退出： 启动 MCP 服务时，在环境中设置 FIRECRAWL_NO_ENDPOINT_FEEDBACK=1（或 FIRECRAWL_DISABLE_ENDPOINT_FEEDBACK=1）。这样将不会注册 firecrawl_feedback 工具，因此 Agent 无法调用它。

使用示例：

{
  "name": "firecrawl_feedback",
  "arguments": {
    "endpoint": "scrape",
    "jobId": "0193f6c5-1234-7890-abcd-1234567890ab",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "tags": ["docs"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing",
    "pageNumbers": [1],
    "metadata": {
      "format": "markdown"
    }
  }
}

返回：

• { success, feedbackId, creditsRefunded, creditsRefundedToday?, dailyRefundCap?, dailyCapReached?, websiteCapReached?, alreadySubmitted?, warning? } JSON。

4. Crawl 工具（firecrawl_crawl）

启动 Crawl 任务，轮询直到任务进入终止状态，并返回最终的 Crawl 状态和数据。

最适合：

• 从多个相关页面提取内容，且需要全面覆盖时。

不建议用于：

• 从单个页面提取内容（使用 scrape）
• 需要关注 Token 限制时（使用 map + scrape 以便更精确地控制）
• 需要快速获取结果时（Crawl 可能很慢）

警告： Crawl 响应可能很大，并可能超过 Token 限制。请限制 Crawl 深度和页面数量，或使用 map + scrape 以便更精确地控制。

常见错误：

• 将 limit 或 maxDiscoveryDepth 设置得过高（会导致 Token 溢出）
• 用 Crawl 处理单个页面（请改用 scrape）

提示词示例：

“获取 example.com/blog 前两层中的所有博客文章。”

使用示例：

{
  "name": "firecrawl_crawl",
  "arguments": {
    "url": "https://example.com/blog/*",
    "maxDiscoveryDepth": 2,
    "limit": 100,
    "allowExternalLinks": false,
    "deduplicateSimilarURLs": true
  }
}

返回：

• 内部轮询后返回最终的 Crawl 状态和数据，包括 id、status、completed、total、creditsUsed、expiresAt、next 和 data。如果稍后需要重新检查任务状态，请使用返回的 id 调用 firecrawl_check_crawl_status。

5. 检查 Crawl 状态（firecrawl_check_crawl_status）

按 ID 检查现有 Crawl 任务的状态和结果。

{
  "name": "firecrawl_check_crawl_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

返回：

• 响应包含 Crawl 任务的状态：

6. Parse 工具（firecrawl_parse）

使用 Firecrawl 的 /v2/parse 端点解析本地文件或托管上传引用。

最适合： PDF、Word 文档、电子表格、HTML 文件及其他需要输出 Markdown 或结构化 JSON 的文档。托管端点使用两步上传流程；直接读取本地文件需要自托管的 FIRECRAWL_API_URL。

不建议用于： 远程 URL（使用 scrape）、单次调用处理多个文件（每个文件调用一次 parse），或截图和点击等仅限浏览器的操作。

托管端点： 它无法读取你的文件系统。使用 filePath 调用 firecrawl_parse，以获取有效期较短的上传命令和 nextToolCall；在本地上传文件后，再使用返回的 uploadRef 调用 firecrawl_parse。上传步骤需要 Firecrawl 身份验证或无密钥层级。在本地 npx firecrawl-mcp 模式下，直接解析文件目前需要 FIRECRAWL_API_URL 指向自托管的 Firecrawl API；仅使用云端 API 密钥的普通本地服务无法通过此工具读取并上传文件。

使用示例：

{
  "name": "firecrawl_parse",
  "arguments": {
    "filePath": "/absolute/path/to/document.pdf",
    "formats": ["markdown"],
    "parsers": ["pdf"],
    "zeroDataRetention": true
  }
}

返回： 已解析的文档内容，或包含 nextToolCall 的托管上传说明。

7. 使用 Scrape JSON 获取结构化数据

若要从已知页面获取结构化数据，请对每个 URL 调用一次 firecrawl_scrape，并设置 formats: ["json"]。在 jsonOptions 中填写提取提示词和 JSON 架构。

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com/product",
    "formats": ["json"],
    "jsonOptions": {
      "prompt": "Extract the product name, price, and description.",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "price": { "type": "number" },
          "description": { "type": "string" }
        },
        "required": ["name", "price"]
      }
    }
  }
}

如果 URL 未知，或数据分布在多个网站上，请使用 firecrawl_agent 进行多来源研究。

8. Agent 工具（firecrawl_agent）

当你不知道 URL，或答案涉及多个网站时，可使用此自主网页研究 Agent 获取结构化数据。描述你需要的字段，可选提供 JSON 架构和种子 URL，然后 Agent 会搜索、浏览、阅读页面，并汇总多个来源的数据，返回 JSON。适用于查询实体及其字段、列表和数据集，以及需要通过导航才能找到数据的页面。对于已知 URL，请改用带 JSON 格式的 firecrawl_scrape。

工作原理：

Agent 会自主搜索网页、跟踪链接、阅读页面并收集数据。该流程以异步方式运行——会立即返回作业 ID，你可以轮询 firecrawl_agent_status，查看任务何时完成并获取结果。

异步工作流：

1. 使用提示词／架构调用 firecrawl_agent → 返回作业 ID
2. Agent 研究期间可继续处理其他工作（复杂查询可能需要几分钟）
3. 使用作业 ID 轮询 firecrawl_agent_status，查看进度
4. 状态为 "completed" 时，响应中会包含提取的数据

最适用场景：

• 不知道确切 URL 的复杂研究任务
• 从多个来源收集数据
• 查找散布在网络各处的信息
• 等待结果期间可以处理其他工作的任务

不建议用于：

• 已知 URL 的简单单页抓取（请使用 JSON 格式的 scrape——速度更快、成本更低）

参数：

• prompt：用自然语言描述你需要的数据（必填，最多 10,000 个字符）
• urls：可选的 URL 数组，用于指定 Agent 重点访问的页面
• schema：可选的 JSON 架构，用于指定结构化输出
• effort：可选。Agent 任务的推理预算，可设为 "low"、"medium" 或 "high"。
• maxCredits：可选的正整数。本次运行的积分支出上限。省略时，API 默认值为 2,500；免费请求的上限为 2,500。
• strictConstrainToURLs：可选的布尔值。若为 true，Agent 只会访问 urls 中的 URL。
• threadId：可选。继续现有线程：使用先前 firecrawl_agent 或 firecrawl_agent_status 结果中的 threadId。省略则开始新线程。后续调用中，省略的 mode、urls、schema 和 exchange 设置会沿用上一轮的设置。
• mode：可选。"extract"（默认）会在每轮返回完整的结构化结果。"chat" 允许后续调用在未请求新数据时直接在 message 中简短回复，而不是重新运行；exchange.requireApproval 需要启用此模式。
• exchange：可选。本轮的 Alexandria 提供方设置，将原样转发至 POST /v2/agent：
  • enabled、toolkits（最多 5 个提供方标识）、maxCalls（1 到 30）、requireApproval（付费调用会以 pendingApproval 结束本轮；同一次调用必须设置 mode: "chat"，后续调用也一样）
  • onTermsRequired：当 Agent 要使用的 Alexandria 提供方需要团队尚未接受的数据条款时，指定应采取的操作。任何模式下都不会调用受条款限制的提供方。后续调用时省略此项会沿用上一轮的值。
    • "skip"（默认）：仅使用已接受条款的提供方作答。状态结果中的 exchange.skippedProviders 会列出本可提供帮助、但受条款限制的提供方。
    • "ask"：行为相同，此外会返回条款 pendingApproval 和包含批准 ID 与提供方要求的 exchange.requiresAction。使用 terms/show 查看条款；由组织管理员在 Firecrawl 控制面板中接受条款。
  • approve：{ approvalId, callIds?, always? } 表示同意上一轮结束时待处理的 pendingApproval。callIds 和 always 仅适用于付费调用审批。
  • decline：{ approvalId } 表示拒绝。拒绝条款提议后，这些提供方在该线程的后续过程中都不会被使用。
  • approve 和 decline 都需要 threadId，且一次只能发送其中一个。 **提供方条款（询问模式）：**没有自动接受模式。当某一轮以条款邀请结束时，状态结果会携带 pendingApproval（kind: "terms"）和 exchange.requiresAction，其中包含 approvalId 和提供方要求。该 API 负载中的任何 terms/accept 描述符都无法通过 MCP 使用。若要使用该提供方：

1. 向用户展示条款（通过 firecrawl_scrape 和 alexandria 调用 terms/show）。
2. 请组织管理员在提供方的网址或数据源设置中接受条款。数据请求不代表同意。
3. 等待管理员在控制面板中确认已接受条款。
4. 继续同一线程：使用相同的 threadId 调用 firecrawl_agent，并传入 exchange.approve: { "approvalId": "..." }。这会恢复研究，不会接受条款。

如果用户拒绝，请改为使用相同的 threadId 调用 firecrawl_agent，并传入 exchange.decline: { "approvalId": "..." }。

提示词示例：

“查找 Firecrawl 的创始人及其背景”

用法示例（启动 Agent，然后轮询结果）：

{
  "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" }
            }
          }
        }
      }
    }
  }
}

然后使用返回的作业 ID，通过 firecrawl_agent_status 轮询。

用法示例（使用 URL——Agent 专注于特定页面）：

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

用法示例（在同一线程中继续提问）：

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "Only keep the startups based in Europe",
    "threadId": "0199a1b2-0000-7000-8000-000000000031"
  }
}

用法示例（管理员在控制面板中确认接受条款后继续线程）：

{
  "name": "firecrawl_agent",
  "arguments": {
    "prompt": "The admin confirmed acceptance of the Apollo terms in the dashboard. Continue.",
    "threadId": "0199a1b2-0000-7000-8000-000000000031",
    "exchange": { "approve": { "approvalId": "0199a1b2-0000-7000-8000-000000000033" } }
  }
}

返回内容：

• 用于查询状态的作业 ID，以及 threadId 和 threadTurn。使用 firecrawl_agent_status 轮询结果。

9. 检查 Agent 状态（firecrawl_agent_status）

检查 Agent 作业的状态，并在完成后获取结果。启动 Agent 后，可使用此工具轮询结果。

**轮询模式：**复杂查询的 Agent 研究可能需要几分钟。请定期（例如，每隔 10-30 秒）轮询此端点，直到状态为 "completed" 或 "failed"。

{
  "name": "firecrawl_agent_status",
  "arguments": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

可能的状态：

• processing：Agent 仍在研究——稍后再查
• completed：研究已完成——响应中包含提取的数据
• failed：发生错误

10. 交互工具（firecrawl_interact）

与新 URL 或已由 firecrawl_scrape 打开的页面进行交互。

**最适合：**点击、输入、导航，以及从动态页面提取状态，无需恢复已弃用的浏览器工具。

用法选项：

• 传入 url，即可在一次 MCP 调用中抓取并打开页面进行交互。
• 传入 scrapeId，即可继续与已抓取的页面交互。
• 若要将浏览器状态（Cookie、localStorage）保存到命名配置文件中，请传入 url，并设置 scrapeOptions: { "profile": { "name": "my-profile", "saveChanges": true } }。会话结束时，firecrawl_interact_stop 会保存该状态。
• url 和 scrapeId 必须且只能传入其中一个，并且还需传入 prompt 或 code。

用法示例：

{
  "name": "firecrawl_interact",
  "arguments": {
    "url": "https://example.com",
    "prompt": "Click the pricing link and summarize the visible plans"
  }
}

**返回内容：**交互结果；在 URL 模式下，还会返回派生的 scrapeId，供后续操作或清理使用。

11. 停止交互工具（firecrawl_interact_stop）

交互完成后，停止与已抓取页面的交互会话。

{
  "name": "firecrawl_interact_stop",
  "arguments": {
    "scrapeId": "scrape-id-here"
  }
}

12. 研究工具（firecrawl_research_*）

通过研究 MCP 工具搜索和查看论文及 GitHub 仓库。

**涵盖内容：**生物医学、生命科学和临床文献（PubMed、bioRxiv、medRxiv）中的论文摘要和全文，以及 arXiv 和其他科学来源。

可用的研究工具：

• firecrawl_research_search_papers：使用自然语言查询搜索论文元数据和摘要，并可选择按作者、类别和日期筛选。
• firecrawl_research_inspect_paper：检索一篇论文 ID（arXiv、PMC、PMID 或 DOI）对应的规范元数据。
• firecrawl_research_related_papers：通过引用图，从一篇或多篇锚定论文拓展搜索。
• firecrawl_research_read_paper：读取特定论文的全文片段。

**最适用场景：**文献综述、论文查找和仓库发现工作流，适用于 Agent 需要专注于研究内容而非一般网页搜索的情况。

使用 categories: ["research"] 的 firecrawl_search 是另一种搜索方式：它将普通网页结果筛选为与研究相关的网站，并返回页面摘要，而非论文记录。当问题涉及文献本身时，请使用这些工具，并针对同一问题提供几种不同的表述方式，因为它们找到的论文会与单次查询不同。

13. 监控工具（firecrawl_monitor_*）

创建和管理定期页面监控。监控会按计划执行抓取或爬取，将每次结果与上次保留的快照进行比较，并可通过 webhook 或电子邮件发送通知。

最适用场景：

• 随时间监控一个或几个页面
• 根据通俗易懂的目标，对有意义的变化发出提醒
• 跟踪检查历史记录和页面级差异

推荐的创建模式：

使用 page 或 pages，并提供 goal。MCP 服务会使用 30 分钟的计划构建监控请求，API 会自动启用有意义变化判断。

设置 goal 后会自动进行有意义变化判断。页面 webhook 会在 monitor.page 事件中提供 isMeaningful 和 judgment。

将目标写成简洁的 2-3 句监控说明。明确哪些情况应触发提醒，保留用户提出的任何范围，并且仅在请求明显表明需要时加入针对意图的排除项。判断器已会处理空白、纯格式变化、请求 ID、跟踪参数、一般元数据和无关的页面界面元素等常见噪声，因此无需在每个目标中重复说明。如果用户的要求含糊，就保持目标宽泛；如果用户要求广泛监控或“任何变化”，就按其要求保留。如果用户表示某些内容无关紧要，请明确写出。

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "page": "https://example.com/pricing",
    "goal": "Alert when pricing, packaging, or launch messaging changes."
  }
}

使用 webhook 监控多个页面：

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "pages": ["https://example.com/pricing", "https://example.com/changelog"],
    "goal": "Alert when pricing, packaging, or launch messaging changes.",
    "webhookUrl": "https://example.com/webhooks/firecrawl"
  }
}

高级创建请求：

当需要指定爬取目标、跟踪 JSON 变化、自定义保留策略或显式控制 judgeEnabled 时，请传入 body。

{
  "name": "firecrawl_monitor_create",
  "arguments": {
    "body": {
      "name": "Docs monitor",
      "schedule": { "text": "hourly", "timezone": "UTC" },
      "goal": "Alert when docs pages add, remove, or materially change API behavior.",
      "targets": [{ "type": "crawl", "url": "https://example.com/docs" }]
    }
  }
}

其他监控工具：

• firecrawl_monitor_list：列出监控项。
• firecrawl_monitor_get：获取一个监控项。
• firecrawl_monitor_update：更新包括 goal、judgeEnabled、webhook 和 notification 在内的字段。
• firecrawl_monitor_run：立即触发检查。
• firecrawl_monitor_delete：删除一个监控项（破坏性操作；仅当用户确实要删除时才调用）。
• firecrawl_monitor_checks：列出检查记录，可按状态筛选。
• firecrawl_monitor_check：获取页面级结果，包括 diff、snapshot、judgment.meaningful 和 judgment.meaningfulChanges。

14. 开发者搜索工具（firecrawl_developer_search）

搜索专为编码 Agent 构建的索引。该索引涵盖 GitHub 议题、已合并的拉取请求、代码库 README 和代码文档。

最适用于： 编程问题，例如代码行为、库或框架、API 契约、错误消息或已知缺陷。

参数：

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}

• query（必填）：开发者问题或搜索词。
• k：排序结果的数量。默认值为 10，最大值为 100。
• skills：设为 "only" 时，仅搜索 Agent 技能文件。

返回： 排序后的结果。每个结果都包含 ID、来源类型（issue、pull_request、readme 或 doc）、URL、标题，以及匹配的 Markdown 片段。

firecrawl_search 搭配 categories: ["developer"] 时，会在网页结果旁搜索同一索引。如果你需要匹配的片段、skills 筛选器，或不希望响应中包含网页结果，请改用此工具。仅搜索端点也提供这两个工具，选择方式相同。

14b. 政府索引搜索工具（firecrawl_gov_search）

搜索美国联邦、州和地方政府来源中的一手法律和监管资料：法规、条例、法典、法院意见及其他政府出版物。

最适用于： 需要适用法律原文或官方政府来源的法律或监管问题。

参数：

{
  "name": "firecrawl_gov_search",
  "arguments": {
    "query": "excessive force claims against police officers",
    "k": 10,
    "courtType": "federal-appellate",
    "cites": "42 U.S.C. § 1983"
  }
}

• query（必填）：法律或监管问题或搜索词。
• k：排序结果的数量。默认值为 10，最大值为 100。
• jurisdiction：仅保留某一司法管辖区的页面：联邦页面使用 "us"，州或领地页面使用 "us-" 加两位字母代码，例如 "us-ca" 或 "us-dc"。
• court：仅保留标注为某一法院的页面，使用 CourtListener 法院 ID，例如 "scotus"、"ca9" 或 "nysd"。
• courtType：仅保留某一法院类型的页面：federal-supreme、federal-appellate、federal-district、federal-bankruptcy、federal-special、military、state-supreme、state-appellate、state-trial、state-special 或 state-attorney-general。
• cites：仅保留引用某一法律或案件的页面，可使用印刷引证，例如 "42 U.S.C. § 1983" 或 "5 U.S. 137"，也可使用引证 ID，例如 "us:usc:42:1983"。
• domain：仅保留来自某个网站的页面，例如 "irs.gov"。

筛选器均为可选项，且可组合使用：结果必须符合所有已设置的筛选条件。筛选器只会保留索引已标注的页面，因此筛选后的搜索可能遗漏相关页面；没有结果并不意味着相关内容不存在。联邦法院和判例集的法院标签最为完整。

返回： 排序后的结果。每个结果都包含位置、标题、URL 和匹配的摘要片段。仅搜索端点也提供此工具。

firecrawl_search 搭配 categories: ["gov"] 时，会搜索相同来源，并将命中结果返回在 data.web 中，且其 category: "gov"。gov 类别不接受这些筛选器，也不能与其他类别组合使用。

15. Alexandria 工具

Firecrawl Alexandria 是一个数据提供商目录，可通过 Firecrawl API 访问。使用者需要持有 Firecrawl API 密钥，且所属团队必须具有 Alexandria 访问权限。无密钥会话（托管或本地）会显示 Alexandria requires an API key on a team with Alexandria access；托管的无密钥会话不会列出 Alexandria 发现工具。

语义发现（firecrawl_search）：

{
  "name": "firecrawl_search",
  "arguments": {
    "query": "podcast conversations about AI agents",
    "sources": ["web", "alexandria"],
    "domainTools": true,
    "limit": 2
  }
}

data.tools 默认返回精简建议，包含提供商、能力和描述。设置 toolDetail: "summary" 可获取元数据和导航信息；设置 toolDetail: "full" 可获取包含输入、响应字段和示例的契约。domainTools: true 会在同一数组中添加与查询提及内容和结果 URL 相关的上下文匹配项。若发现功能不可用，请检查 warning。搜索需要提供查询，且不接受目录遍历筛选器。完整 MCP 界面和仅搜索界面均支持此发现功能。

渐进式披露（firecrawl_find_tools）：

{
  "name": "firecrawl_find_tools",
  "arguments": {
    "providers": ["particle"],
    "capabilities": ["podcasts/episodes/search"],
    "expand": ["options", "response", "examples"],
    "limit": 2
  }
}

不带参数开始查看分类，然后逐步缩小目录范围：

参数	结果
{}	分类和简短描述
{"categories":["podcasts"]}	该分类下的提供方
{"categories":["podcasts"],"providers":["particle"]}	精简的工具名称和描述
{"providers":["particle"],"capabilities":["podcasts/episodes/search"]}	所选工具的完整输入、约束、响应和示例

无需逐级跳转。显式设置 level 可选择 categories、providers、groups 或 tools；显式设置 expand 可选择契约部分。即使选择了某项能力，expand: [] 也会保持结果精简。若要获取广泛的完整契约，请显式请求 level: "tools" 和 expand: ["options", "response", "examples"]。 URL 可用于上下文发现，但不会抓取页面。除非设置 includeCosts: true，否则工具结果会省略每项能力的费用；后续调用的 nextTool 参数会保留此设置。

结果位于 data.alexandria[0].data 中。通过调用对应的 name 并传入其 arguments，跟进某项的 nextTool；页面的 nextTool 会推进分页。现有的 next 对象仍是可通过 firecrawl_scrape 使用的 Alexandria 发现调用。发现操作不消耗额度，也不会执行提供方工具。执行前请先阅读所选工具的完整契约。

这些控制项需要匹配的 Alexandria API 部署。

**执行（通过 firecrawl_scrape 使用 alexandria）：**传入 alexandria 而非 url（两者必须且只能提供一个；也可以提供 requestId 和 timeout）。可接受单次调用或最多包含十次调用的数组。

{
  "name": "firecrawl_scrape",
  "arguments": {
    "alexandria": [
      {
        "provider": "fred",
        "capability": "series/observations",
        "options": { "series_id": "CPIAUCSL" }
      }
    ]
  }
}

返回：{ success, scrape_id, requestId, data: { alexandria: [...], creditsCost } }。每个条目要么是结果（provider、capability、data、records、upstreamStatus），要么是带有 code 的 error；提供方出错不会导致整个批次失败，且 data.creditsCost 是本次请求收取的总额。Alexandria 错误响应正文（无 Alexandria 访问权限时的 403，以及计费状态 402/409）会连同其 code 一并原样返回。

执行时会生成一个 x-request-id，并在成功或失败时返回。若要重试，请使用完全相同的请求载荷和该 requestId；结果不确定时不要创建新的 ID。可用额度由 API 检查。

若团队尚未接受某个 Alexandria 提供方的条款，该提供方会在执行任何操作前失败，并返回 HTTP 403 和以下正文：

{
  "success": false,
  "code": "THIRD_PARTY_DATA_TERMS_REQUIRED",
  "error": "An organization admin must accept the benzinga provider's terms (version 2026-09-12-placeholder) before this request can run. Accept them at https://www.firecrawl.dev/app/alexandria/benzinga",
  "requiresAction": {
    "type": "accept_terms",
    "terms": "benzinga",
    "version": "2026-09-12-placeholder",
    "url": "https://www.firecrawl.dev/app/alexandria/benzinga"
  }
}

工具结果会将其作为错误返回，其中 structuredContent 包含 code、status: 403、requestId、未作更改的 requiresAction 对象，以及 next_actions（依次为 human_action_required 和 retry_same_request）。接受条款属于法律行为，因此应由组织管理员在 Firecrawl 控制面板中接受，而非通过 MCP 接受。使用返回的 nextTool 调用，通过 firecrawl_scrape 和 alexandria: [{provider: "firecrawl", capability: "terms/show", options: {provider: "<provider>"}}] 阅读协议；此调用应与提供方执行请求分开，并将协议内容展示给用户。随后，组织管理员可在 requiresAction.url 指向的页面或 https://www.firecrawl.dev/app/settings?tab=data-sources 接受协议。 firecrawl_scrape 会拒绝所有其他 terms/* 能力，因此不会更改账户。请求数据不代表同意，也不会自动接受条款或在结果不确定时进行重试。 此次被阻止的数据检索不会收取任何额度。管理员确认接受后，使用完全相同的请求载荷和 requestId 再次调用同一工具。

16. 积分用量工具

此工具需要经过身份验证的 Firecrawl 账户，且为只读工具。

• firecrawl_credit_usage 默认为 { "view": "current" }，并返回 remainingCredits、planCredits、billingPeriodStart 和 billingPeriodEnd。如果团队有额外充值或赠送积分，剩余积分可能高于套餐积分。
• 传入 { "view": "historical" }，即可获取包含 startDate、endDate 和 creditsUsed 的自然月周期。传入 { "byApiKey": true } 也会选择历史视图，并按 API 密钥拆分周期；此时每一行都会包含 apiKey。改为传入 { "byEndpoint": true }，则会按使用积分的端点（scrape、search、crawl、map、agent、...）拆分周期；此时每一行都会包含 endpoint。传入 { "bin": "day" }，则会按 UTC 天拆分周期，而非按自然月拆分。不要同时使用 byApiKey 和 byEndpoint，也不要将其中任何一项与 { "view": "current" } 一起使用。最新周期的 endDate 可能为 null。如果 Firecrawl API 尚未提供端点拆分或按天统计，结果会附带 notice 和月度数据。

编程式使用（不稳定）

此软件包还提供了一个库入口，可将服务嵌入其他运行时。该入口不稳定：其 API、选项和类型可能在任何版本中发生变化，包括次要版本和补丁版本，因此请固定使用确切版本。

npm install --save-exact firecrawl-mcp zod

此示例使用 zod 定义工具参数，因此嵌入项目需将其作为自身依赖项安装。

import { createFirecrawlMcpServer } from 'firecrawl-mcp/server';
import { z } from 'zod';

const server = createFirecrawlMcpServer({
  transport: 'httpStream',
  apiKey: process.env.FIRECRAWL_API_KEY,
  unstable_hooks: {
    registerExtraTools: (registrar) => {
      registrar.addTool({
        name: 'my_tool',
        description: 'An extra tool served next to the Firecrawl tools.',
        parameters: z.object({ text: z.string() }),
        execute: async ({ text }) => text,
      });
    },
  },
});

await server.start({
  transportType: 'httpStream',
  httpStream: { port: 3000, host: '127.0.0.1', endpoint: '/mcp', stateless: true },
});
// MCP endpoint: http://127.0.0.1:3000/mcp

请显式设置 host。如果不设置，服务会监听 localhost，而 Node 会将其绑定到单个地址（通常只有 ::1），导致发往 127.0.0.1 的请求被拒绝。只有在网络访问控制措施到位，或使用 unstable_hooks.authenticate 检查的情况下，才使用 0.0.0.0 或 :: 接受来自其他机器的连接：如果没有这些措施，所有能够访问该端口的调用方都会使用配置的 apiKey 获得服务。

除非明确要求，否则此库不会检查 Host 或 Origin，且其 CORS 标头允许任何来源。在同一台机器上可从浏览器访问的服务应传入 httpStream.allowedHosts（例如 ['localhost', '127.0.0.1', '[::1]']）：如果请求的 Host 或 Origin 标头指向其他主机，则会收到 403（健康检查路径上的 GET 和 HEAD 请求除外），且 CORS 标头会回显允许的来源。命令行在本地 HTTP 模式下会设置此列表。

选项与 CLI 的环境变量对应：apiUrl、apiKey、transport、logging、safeMode、fileAccess（local 或 upload）、requireCredential、searchFeedback 和 endpointFeedback。unstable_hooks 接受：

Hook	用途
authenticate(request)	为请求解析会话；抛出 Response 以拒绝请求。
wrapTool(tool)	装饰每个已注册的工具。
onToolResult(event)	观察每次工具调用的开始和结果。
instructions	服务说明，或用于从默认说明中选择内容的函数。
registerExtraTools(registrar, context)	在内置工具之后添加工具。
outboundRequest(session)	为每个 Firecrawl API 请求提供凭据和额外标头。
beforeKeylessRequest(session, origin)	通过抛出异常拒绝无密钥请求。
toolFilter(name)	从实例中排除内置工具。
configureHttp(app)	添加 HTTP 路由。
oauth.protectedResource	提供 OAuth 受保护资源元数据。

此服务基于官方 MCP TypeScript SDK（@modelcontextprotocol/server）构建。请使用 firecrawl-mcp/server 导出的类型（Session、ToolDefinition、ToolRegistrar、FirecrawlMcpServerHooks 等），而不要使用 SDK 自身的类型。

该入口还导出了内置工具使用的辅助函数，例如 recoveryPayload、normalizeHeader、requestOrigin、isRuntimeUserAgent、initializeClientSlug、searchToolBaseFields、searchOutputSchema 和 structuredCompact，以便额外工具和钩子与内置行为保持一致。这些辅助函数同样不稳定。

日志系统

该服务包含全面的日志记录：

• 操作状态和进度
• 性能指标
• 速率限制跟踪
• 错误情况

日志消息示例：

[INFO] Firecrawl MCP Server initialized successfully
[INFO] Starting scrape for URL: https://example.com
[ERROR] Rate limit exceeded

错误处理

该服务提供可靠的错误处理：

• 向 MCP 客户端显示 API 速率限制错误
• 详细的错误消息
• 网络弹性

错误响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "Error: Rate limit exceeded"
    }
  ],
  "isError": true
}

开发

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

贡献

1. Fork 该代码仓库
2. 创建功能分支
3. 运行测试：npm test
4. 提交拉取请求

感谢贡献者

感谢 @vrknetha、@cawstudios 提供初始实现！

感谢 MCP.so 和 Klavis AI 提供托管服务，也感谢 @gstarwd、@xiangkaiz 和 @zihaolin96 集成我们的服务。

许可证

MIT 许可证——详情请参阅 LICENSE 文件

结构化数据和大型结果

经过身份验证的搜索默认返回网页结果、语义 Alexandria 工具和域名匹配项。从实际问题入手。对于直接的语义工具查找、选定契约或渐进式浏览，请使用 firecrawl_find_tools：类别 → 提供商 → 精简工具 → 选定契约。通过 firecrawl_scrape 执行工具；普通 URL 抓取和搜索不会自动执行提供商工具。

对于选定的契约，优先使用 expand: ["options", "response"]，仅当输入格式不明确时才请求示例。一起检查相关功能，并复用返回的契约。

对于可能产生大型结果的工作流，请在执行前提供并保留顶层 requestId。即使客户端拒绝响应，该 ID 仍然可用。常规 URL 抓取则使用返回的抓取 ID。

对于大型的已保留工作流结果或常规抓取结果，使用以下参数调用 firecrawl_scrape：

{
  "alexandria": {
    "provider": "firecrawl",
    "capability": "bash",
    "options": {
      "requestId": "<source-request-or-scrape-id>",
      "command": "ls -lh"
    }
  }
}

读取 data.alexandria[0].data 中的 stdout、stderr、exitCode 和 workspaceId。接着使用 options: {workspaceId, command}，通过 jq 检查 response.json，或通过有界文本命令检查常规抓取的 document.md。只保留必要的输出。源数据加载必须作为独立调用；其嵌套源 ID 与顶层执行请求 ID 不同。工作区在闲置五分钟后过期，并非每个结果都会保留（包括 ZDR 和 API 提供商工作流负载）。不支持搜索 ID。

对于工作流源，response.json 会保留 API 信封：先选择 .data.alexandria[].data，然后在非空时选择选定契约的 response.key。如果已知数据结构，请在一条 Bash 命令中合并相关计数和投影，而不要反复检查键。

对于超过 20,000 个估算令牌的成功 Alexandria 执行响应（序列化后的 UTF-8 字节数除以 4），在远程 Bash 确认完整批次可访问后，会返回一个简短的交接信息。按照 nextTool 检查保留的数据。这会额外增加一次 Bash 调用，并启动一个闲置 TTL 为五分钟的工作区。完整负载会得到保留。如果确认失败，原始响应仍会内联返回。搜索、普通 URL 抓取、错误响应和 Firecrawl 实用工具调用不受影响。此交付预算不衡量客户端剩余的上下文；不会添加进程本地结果缓存。如果可使用本地文件系统工具，也可以保存 CLI 输出并读取选定部分。

CLI 发现流程对应以下 MCP 调用：

意图	工具	参数
网页 + 语义 + 域名工具	firecrawl_search	{"query":"<user question>"}
仅语义工具	firecrawl_search	{"query":"<user question>","sources":["alexandria"]}
类别	firecrawl_find_tools	{}
类别中的提供商	firecrawl_find_tools	{"categories":["<category-id>"]}
精简的提供商工具	firecrawl_find_tools	{"providers":["<provider-id>"]}
选定契约	firecrawl_find_tools	{"providers":["<provider-id>"],"capabilities":["<capability-id>"]}
执行	firecrawl_scrape	{"alexandria":{"provider":"<provider-id>","capability":"<capability-id>","options":{"<required-field>":"<value>"}}}

「查找工具」和执行功能在完整界面和搜索界面上均可用。如果搜索结果中已包含完整契约，请直接复用，而不要再次调用发现功能。只有在需要更多结果时，才使用返回的 nextTool 导航。

Alexandria 会话反馈

现有的 firecrawl_feedback 工具接受 endpoint: "alexandria"：

{
  "endpoint": "alexandria",
  "rating": "partial",
  "requestedWebsite": {
    "url": "https://example.com",
    "requestedFunctionality": "Find records and download their attachments"
  },
  "objective": "Compare contract requirements across agencies before bidding",
  "rationale": "Found summaries but could not retrieve attachments"
}

可选的 objective 是会话的根本目标：Agent 或其用户最终想要完成的事情，而不只是 requestedWebsite 中的单个网站。

此操作使用经过身份验证的 POST /v2/feedback，且不需要任务 ID。反馈必须在团队最近一次 Alexandria 搜索、发现或执行后的 20 分钟内提交；超时后提交的反馈会被拒绝，并返回 FEEDBACK_WINDOW_EXPIRED。符合条件的反馈可退还 1 个积分，但受每日上限约束：每个网站 10 个积分，每个团队 100 个积分（UTC 日）。超过任一上限后，反馈仍会被记录，但不会退款，响应中会设置 websiteCapReached 或 dailyCapReached。可选的 providerFeedback 和 capabilityFeedback 数组用于描述覆盖范围缺口和执行问题；工具架构列出了支持的问题值。new_capability_request 需要提供 requestedFunctionality；missing_capability（提供商存在，但缺少该能力）则不需要。现有的反馈退出选项和身份验证控制仍然适用。

符合条件的 Alexandria 执行和发现结果会包含一个 feedbackTool 指针，其中包含工具名称和参数框架。对于 Firecrawl 内部调用（例如 bash），以及未注册 firecrawl_feedback 时（设置了 FIRECRAWL_NO_ENDPOINT_FEEDBACK 或启动时未提供密钥），则不会包含该指针。