Firecrawl MCP

官方

为Cursor和Claude等LLM客户端添加强大的网页抓取和搜索功能。

访问 firecrawl.link

你可以用 Firecrawl MCP 做什么？

  • 抓取已知 URL — 让助手将单个页面抓取为干净的 Markdown 或符合你通过 firecrawl_scrape 提供的 schema 的结构化 JSON。
  • 发现站点 URL — 让助手使用 firecrawl_map 列出站点上已编入索引的 URL，然后再决定要抓取哪些页面。
  • 搜索网络 — 使用 firecrawl_search 获取查询的排名结果，并可选地为部分结果抓取完整页面内容。
  • 爬取多个页面 — 使用 firecrawl_crawl 在整个站点中提取内容，并通过 limit、includePaths/excludePaths 或 maxDiscoveryDepth 限定范围。
  • 驱动浏览器 — 使用 firecrawl_interact 点击、输入、填写表单或导航动态页面，并通过 scrapeId 继续会话。
  • 检查额度使用情况 — 使用 firecrawl_credit_usage 询问还剩多少 Firecrawl 额度，或这些额度花在了哪里。

文档

Firecrawl MCP Server

一个 Model Context Protocol (MCP) 服务器，将 Firecrawl——面向 AI 智能体的上下文 API——带给兼容 MCP 的客户端：搜索、抓取并与实时网络交互，返回干净的 Markdown 或结构化数据。

非常感谢 @vrknetha、@knacklabs 的初始实现！

功能特性

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

在 MCP.so 的 playground 上试用我们的 MCP Server，或在 Klavis AI 上试用。

何时使用此服务器

  • 当你有已知 URL，并希望将其内容获取为 markdown 或符合你所提供 schema 的 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_* 工具。
  • 使用 firecrawl_credit_usage 查看剩余额度或额度支出情况，可按月或按天查看，并可选按端点或 API key 细分。
  • 当你需要在你自己的多个步骤中保持浏览器会话打开，并使用你自己的重试和终止逻辑时，请考虑其他方案：每次 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 key）仅暴露 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 key 即可使用（有速率限制）。其他工具如 crawl、map 和 agent 仍需要 key。

只要用户能够注册，就优先使用 OAuth 或 API key。它可以解锁完整的工具集和更高的限制。

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

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

对于 API key 连接（例如无人值守的集成），请将服务器 URL 保持为：

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

然后使用以下内容配置客户端的安全 header 或密钥设置：

Authorization: Bearer <FIRECRAWL_API_KEY>

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

为你的集成命名

通过 HTTP 连接的集成可以使用 X-Firecrawl-Origin header 为自身命名，例如 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 Server 配置指南

在 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. 输入以下内容：
    • Name: "firecrawl-mcp"（或你偏好的名称）
    • Type: "command"
    • 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 key。如果你还没有，可以创建一个账户并从 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 header 指定了其他主机，或其 Origin header 指定了其他站点，则会收到 403，并且 CORS header 会回显允许的来源而不是 *。对 /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 header。仅当服务器前面的某个组件自身会检查主机和来源时才这样做。

使用 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>（或一个 digest）。

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 上发布端口；除非客户端必须提供自己的 key，否则不要更广泛地暴露它。设置 FIRECRAWL_API_URL 以使用自托管的 Firecrawl API。容器以非特权用户 node 运行。服务器在 Host 和 Origin header 中仅应答 localhost、127.0.0.1 和 [::1]，因此 -p 127.0.0.1:3000:3000 映射可直接使用；要通过其他名称访问它，请设置 -e FIRECRAWL_MCP_ALLOWED_HOSTS=<host>（参见 Streamable HTTP 本地模式）。

在 VS Code 上运行

要一键安装，请点击下面的某个安装按钮...

Install with NPX in VS Code Install with NPX in VS Code Insiders

要手动安装，请将以下 JSON 块添加到 VS Code 中的 User Settings (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 key
    • 使用云端 API（默认）时必需
    • 使用带有 FIRECRAWL_API_URL 的自托管实例时可选
  • FIRECRAWL_API_URL（可选）：用于自托管实例的自定义 API 端点
    • 示例：https://firecrawl.your-domain.com
    • 如果未提供，将使用云端 API（需要 API key）
  • FIRECRAWL_INTEGRATION（可选）：用于启动此服务器的应用（例如编辑器扩展）的集成标签
    • 作为 scrape、batch scrape、crawl、map、search、extract、agent、parse、interact 和 feedback 请求的 integration 字段发送
    • 使用以 _ 开头的值，例如 _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 服务器会将其解析到的任何凭据作为 Authorization: Bearer … 转发给 Firecrawl API。

  • 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。
  • stdio： 使用 FIRECRAWL_OAUTH_TOKEN 提供静态访问令牌，或继续使用 FIRECRAWL_API_KEY 提供 API 密钥。

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

CLOUD_SERVICE=true

CLOUD_SERVICE=true 通过可流式 HTTP 在 PORT 上提供这些工具（默认 3000，绑定到 0.0.0.0），并采用更严格的默认设置：每个请求都必须携带凭据（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，它会搜索论文摘要和全文。search 配合 categories: ["research"] 是另一回事：对普通网页结果进行网站过滤。
  • 如果你需要返回结构化数据的多源研究、不知道 URL，或答案横跨多个站点（某个实体及其字段、列表、数据集）：使用 agent
  • 如果你想分析整个站点或某个部分： 使用 crawl（注意限制！）
  • 如果你需要交互式浏览器自动化（点击、输入、导航）：使用 interact 并传入 URL 以打开新页面，或者在你已经抓取过页面或需要更精细的抓取控制时使用 scrape + interact
  • 如果你需要来自已编目提供商（Alexandria）的数据：使用 sources: ["alexandria"] 搜索，用 find_tools 检查选定的契约，并用 scrape alexandria 执行它

快速参考表

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

格式选择指南

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

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

可用工具

1. Scrape 工具（firecrawl_scrape）

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

最适合：

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

不推荐用于：

  • 从多个页面提取内容（对已知 URL 使用重复的 scrape 调用，或先 map + scrape 发现 URL，或使用 crawl 获取完整页面内容）
  • 当你不确定哪个页面包含信息时（使用 search）

常见错误：

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

选择正确的格式：

  • JSON 格式（首选）： 对于大多数用例，使用带 schema 的 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 格式： 提取全面的品牌标识（颜色、字体、排版、间距、logo、UI 组件），用于设计分析或风格复刻。 隐私： 设置 redactPII: true 可返回已脱敏个人可识别信息的内容。 配合 CLOUD_SERVICE=true 时： scrape 为只读。它不接受浏览器 actions，也无法接受提供商条款。指定 profile 会加载已保存的浏览器状态而不向其保存更改，完整端点的 firecrawl_search 也以同样方式对待 scrapeOptions.profile。要将浏览器状态保存到配置文件，请使用 firecrawl_interact 打开页面（见下文）。组织管理员在仪表板中接受条款。

返回：

  • JSON 结构化数据、markdown、品牌配置文件或指定的其他格式。

2. Map 工具（firecrawl_map）

映射网站以发现站点上所有已索引的 URL。

最适合：

  • 在决定抓取什么之前发现网站上的 URL
  • 查找网站的特定部分

不推荐用于：

  • 当你已经知道需要哪个特定 URL 时（使用 scrape）
  • 当你需要页面内容时（先 map 再 scrape）

常见错误：

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

提示词示例：

"列出 example.com 上的所有 URL。"

用法示例：

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

返回：

  • 站点上找到的 URL 数组

3. Search 工具（firecrawl_search）

在网上搜索，并可选地从搜索结果中提取内容。

最适合：

  • 在多个网站中查找特定信息，当你不确定哪个网站有该信息时。
  • 当你需要与查询最相关的内容时

不推荐用于：

  • 当你已经知道要抓取哪个网站时（使用 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"] 会将普通网页结果过滤为研究相关网站。

返回：

  • 按来源分组的搜索结果（data.web、data.images、data.news），带有可选的抓取内容，以及一个 id 字段。每个结果都带有一个 source 和一个从 1 开始索引的 position，在其所属分组内从 1 开始编号——请将该对直接复制到 firecrawl_search_feedback 的 valuableResults 中，而不是去数数组元素。在你使用结果后，将该 id 传给 firecrawl_search_feedback，以返还 1 个积分（搜索花费 2 个积分）并提升搜索质量。

提示词示例：

"比较各科技公司的远程办公津贴政策。"

3b. Search Feedback 工具（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。它是一个数组，包含智能体预期找到但实际未找到的特定内容片段。每个缺失的主题对应一个条目；这些条目会跨团队汇总，告诉我们接下来应该索引什么。为了获得有用的结果，请使用 valuableResults，并在每个结果上标记 source/position 对——结果会分组，每组独立从 1 开始编号，因此两者都是必需的。请列出每一个有用的结果（未列出的结果会被视为无用），并将 valuableSources 保留给不在返回结果中的有用 URL。

每日退款上限（每个团队、每个 UTC 日，默认 100 积分）。 一旦某个团队的 creditsRefundedToday 达到 dailyRefundCap，后续提交仍会记录反馈，但不再退还积分。响应会设置 dailyCapReached: true。当智能体看到该标志时，应在当天剩余时间（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 工具将不会被注册，因此智能体无法调用它。

用法示例：

{
  "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. 爬取工具（firecrawl_crawl）

启动爬取任务，轮询直到达到终止状态，并返回最终的爬取状态/数据。

最适合：

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

不推荐用于：

  • 从单个页面提取内容（请使用 scrape）
  • 当 token 限制是问题时（使用 map + scrape 以获得更严格的控制）
  • 当你需要快速结果时（爬取可能很慢）

警告： 爬取响应可能非常大，可能超出 token 限制。限制爬取深度和页面数量，或使用 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
  }
}

返回：

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

5. 检查爬取状态（firecrawl_check_crawl_status）

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

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

返回：

  • 响应包含爬取任务的状态：

6. 解析工具（firecrawl_parse）

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

最适合： 需要 markdown 或结构化 JSON 输出的 PDF、Word 文档、电子表格、HTML 文件和其他文档。托管端点使用两步上传流程；本地直接文件读取需要自托管的 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 获取结构化数据

对于已知页面的结构化数据，请使用 formats: ["json"] 对每个 URL 调用一次 firecrawl_scrape。将提取提示和 JSON schema 放入 jsonOptions。

{
  "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. 智能体工具（firecrawl_agent）

自主网络研究智能体，当你不知道 URL 或答案跨越多个站点时返回结构化数据。描述你需要的字段，可选地传入 JSON schema 和种子 URL，智能体会搜索、导航、读取页面，并返回跨源汇总的 JSON。它适用于实体及其字段、列表和数据集，以及需要导航才能到达数据的页面。对于单个已知 URL，请改用 firecrawl_scrape 配合 JSON 格式。

工作原理：

智能体执行网络搜索、跟随链接、读取页面并自主收集数据。此过程异步运行——它会立即返回任务 ID，你通过轮询 firecrawl_agent_status 来检查何时完成并获取结果。

异步工作流：

  1. 使用你的提示/schema 调用 firecrawl_agent → 返回任务 ID
  2. 在智能体研究期间做其他工作（复杂查询可能需要几分钟）
  3. 使用任务 ID 轮询 firecrawl_agent_status 以检查进度
  4. 当状态为“completed”时，响应包含提取的数据

最适合：

  • 你不知道确切 URL 的复杂研究任务
  • 多源数据收集
  • 查找分散在网络上的信息
  • 你可以在等待结果时做其他工作的任务

不推荐用于：

  • 你知道 URL 的简单单页抓取（请使用带 JSON 格式的 scrape——更快且更便宜）

参数：

  • prompt：你想要的数据的自然语言描述（必需，最多 10,000 个字符）
  • urls：可选的 URL 数组，用于让智能体聚焦于特定页面
  • schema：可选的 JSON schema，用于结构化输出
  • effort：可选。智能体任务的 "low"、"medium" 或 "high" 推理预算。
  • maxCredits：可选的正整数。本次运行的积分消费上限。省略时 API 默认为 2,500，并将免费请求上限设为 2,500。
  • strictConstrainToURLs：可选的布尔值。如果为 true，智能体只访问 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 个提供商 slug）、maxCalls（1 到 30）、requireApproval（付费调用以 pendingApproval 结束本轮；需要在同一次调用中设置 mode: "chat"，即使在后续调用中也是如此）
    • onTermsRequired：当智能体将要使用的 Alexandria 提供商需要你的团队尚未接受的数据条款时该怎么做。受门控的提供商在任何模式下都不会被调用。在后续调用中省略会保留上一轮的值。
      • "skip"（默认）：仅使用已接受的提供商作答。状态结果上的 exchange.skippedProviders 会列出本可提供帮助的受门控提供商。
      • "ask"：同上，外加条款 pendingApproval 和 exchange.requiresAction，包含批准 ID 和提供商要求。使用 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. 向用户展示条款（terms/show 到 firecrawl_scrape，配合 alexandria）。
  2. 引导组织管理员在提供商的 URL 或数据源设置处接受条款。数据请求不等于同意。
  3. 等待管理员在仪表板中确认接受。
  4. 继续同一线程：使用相同的 threadId 和 exchange.approve: { "approvalId": "..." } 调用 firecrawl_agent。这会恢复研究，并不会接受条款。

如果用户说“否”，请改用相同的 threadId 和 exchange.decline: { "approvalId": "..." } 调用 firecrawl_agent。

提示示例：

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

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

{
  "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——智能体聚焦于特定页面）：

{
  "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. 检查智能体状态（firecrawl_agent_status）

检查智能体任务的状态，并在完成时获取结果。在启动智能体后，使用此工具轮询结果。

轮询模式： 对于复杂查询，智能体研究可能需要几分钟。定期轮询此端点（例如每 10-30 秒一次），直到状态为“completed”或“failed”。

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

可能的状态：

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

10. 交互工具（firecrawl_interact）

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

最适合： 在不恢复已弃用浏览器工具的情况下，对动态页面进行点击、输入、导航和状态提取。

用法选项：

  • 传入 url，在一次 MCP 调用中抓取并打开页面以进行交互。
  • 传入 scrapeId，继续与现有已抓取页面交互。
  • 要将浏览器状态（cookies、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：读取特定论文的全文段落。

最适合： 文献综述、论文查找和仓库发现工作流，其中智能体需要专注的研究界面，而不是通用网络搜索。

firecrawl_search 与 categories: ["research"] 是不同的界面：它将普通网络结果筛选为研究相关网站，并返回页面片段，而不是论文记录。当问题涉及文献本身时使用这些工具，并传入同一问题的多个不同表述，因为它们会呈现与单次查询不同的论文。

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）

搜索为编码智能体构建的索引。该索引涵盖 GitHub issue、已合并的 pull request、仓库 README 和代码文档。

最适合： 编程问题：代码行为、库或框架、API 契约、错误消息或已知 bug。

参数：

{
  "name": "firecrawl_developer_search",
  "arguments": {
    "query": "how do I configure retries",
    "k": 10,
    "skills": "only"
  }
}
  • query（必填）：开发者问题或搜索短语。
  • k：排序结果的数量。默认值为 10，最大值为 100。
  • skills：设置为 "only" 以仅搜索智能体技能文件。

返回： 排序结果。每个结果包含 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 对象仍可作为 Alexandria 发现调用，通过 firecrawl_scrape 使用。发现不消耗信用，且从不执行提供方工具。执行前请阅读选定的完整契约。

这些控制项需要匹配的 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。当团队有充值或赠额时，剩余额度可能超过套餐额度。
  • 对于包含 startDate、endDate 和 creditsUsed 的日历月周期，传入 { "view": "historical" }。传入 { "byApiKey": true } 还会选择历史视图，并按 API key 拆分周期；此时每一行都包含 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 接受：

钩子用途
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 个估计 token（序列化 UTF-8 字节数除以四）的成功 Alexandria 执行响应，会在远程 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 数组描述覆盖缺口和执行问题；工具 schema 列出了支持的问题值。new_capability_request 需要 requestedFunctionality；missing_capability（提供方存在但缺少该能力）则不需要。现有的反馈退出和身份验证控制仍然适用。

符合条件的 Alexandria 执行和发现结果包含一个 feedbackTool 指针，其中带有工具名称和参数骨架。对于 Firecrawl 内部调用（例如 bash）以及当 firecrawl_feedback 未注册时（FIRECRAWL_NO_ENDPOINT_FEEDBACK 或无密钥启动），该指针会被省略。