Firecrawl MCP 安装指南（面向 AI Agent）

本文档记录了在实际环境中安装、配置 Firecrawl MCP Server 的完整流程、踩坑记录和解决方案。所有内容均为实际操作验证，不含推测。

一、前置条件

一个 Firecrawl API Key，格式为 fc- 开头的字符串（例如 fc-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）
获取地址：https://www.firecrawl.dev/app/api-keys
需要网络能访问 mcp.firecrawl.dev（Cloud 模式）或本地有 Node.js 18+（stdio 模式）

二、两种接入模式

Firecrawl MCP 有两种主要的接入模式，根据你的 AI Agent 平台选择：

模式 A：Firecrawl Cloud MCP（Streamable HTTP 远程托管）

适用场景： Hermes Agent、OpenClaw、以及所有支持 HTTP MCP 的 Agent 平台

原理： Firecrawl 官方托管了一个 MCP Server，API Key 直接嵌入 URL 路径中。无需本地安装 Node.js 或 npm。

MCP Server 信息（已验证）：

Server 名称：firecrawl-fastmcp
Server 版本：3.0.0
协议版本：2025-03-26
传输协议：Streamable HTTP（SSE 格式响应）
URL 格式：https://mcp.firecrawl.dev/{YOUR_API_KEY}/v2/mcp

模式 B：本地 stdio 模式（npx 启动）

适用场景： Claude Desktop、Cursor、VS Code、Claude Code、Codex 等支持 stdio MCP 的客户端

原理： 本地通过 npx 启动一个 MCP Server 进程，通过 stdin/stdout 通信。

npm 包名： firecrawl-mcp（当前最新版本 3.20.2，发布于 2026-06-01）

三、模式 A 配置详情（已验证）

3.1 Hermes Agent 中的配置

⚠️ 重要： 配置路径取决于你的 Hermes profile，不是固定的 ~/.hermes/。先确认路径：
bash
echo $HERMES_HOME
# 如果为空，检查 ~/.hermes/profiles/ 下有哪些 profile
ls ~/.hermes/profiles/

配置文件位置：

场景	必需配置路径	可选 `.env` 路径
有明确 profile	`$HERMES_HOME/config.yaml`	`$HERMES_HOME/.env`
使用默认 profile	`~/.hermes/config.yaml`	`~/.hermes/.env`

常见错误： Agent 把自己当成 default profile，直接修改全局目录 ~/.hermes/，但实际应该写到 profile 目录（如 ~/.hermes/profiles/xxx-agent/）。

当前 Firecrawl Cloud MCP 的必需配置只有 config.yaml 里的 URL。 API Key 嵌在 URL 路径中，Hermes 连接 MCP 时实际读取的是 mcp_servers.firecrawl.url。

正确操作：

bash

# 1. 确认当前 profile 路径
echo $HERMES_HOME
# 输出示例: /home/ubuntu/.hermes/profiles/my-agent

# 2. 编辑对应的 config.yaml
# default profile: ~/.hermes/config.yaml
# 非 default profile: $HERMES_HOME/config.yaml

yaml

mcp_servers:
  firecrawl:
    url: https://mcp.firecrawl.dev/fc-YOUR_API_KEY/v2/mcp

关于 .env： 对当前 Hermes 连接 Firecrawl Cloud MCP 来说，.env 里的 FIRECRAWL_API_KEY=... 不是必需项。实测临时禁用 .env 中的 FIRECRAWL_API_KEY 后，Hermes 仍可通过 config.yaml 的 URL 成功发现 Firecrawl 工具。只有当其他功能或其他模式明确读取该环境变量时，才需要额外设置。

验证命令：

bash

hermes tools list | grep firecrawl
# 预期输出: firecrawl  all tools enabled

3.2 用 curl 手动验证 MCP 连接

bash

# 1. 发送 initialize 请求
curl -s -X POST https://mcp.firecrawl.dev/fc-YOUR_API_KEY/v2/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'

预期返回（SSE 格式）：

event: message
id: ...
data: {"result":{"protocolVersion":"2025-03-26","capabilities":{"tools":{},"logging":{}},"serverInfo":{"name":"firecrawl-fastmcp","version":"3.0.0"},...},"jsonrpc":"2.0","id":1}

3.3 ⚠️ 踩坑：Accept Header 必须包含 text/event-stream

问题： 如果 curl 请求不带 Accept: application/json, text/event-stream，会返回错误：

json

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}

解决： 所有 HTTP 请求必须带上完整的 Accept header：

Accept: application/json, text/event-stream

影响范围： 如果你使用的 MCP Client 框架不自动添加这个 header，连接会直接失败。

3.4 ⚠️ 踩坑：URL 路径中的 API Key

发现： Cloud MCP 的 URL 将 API Key 直接作为路径的一部分（而非 header），格式为：

https://mcp.firecrawl.dev/{API_KEY}/v2/mcp

这意味着：

API Key 是 URL 的一部分，不是环境变量传入
如果 Key 格式错误或过期，服务器不会返回明确错误，而是初始化可能成功但后续调用失败
确保你的 API Key 是 fc- 开头的完整字符串

四、模式 B 配置详情（已从官方文档验证）

4.1 Claude Desktop

配置文件路径：claude_desktop_config.json

json

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

4.2 Cursor

配置位置：Settings → Features → MCP Servers → "+ Add new global MCP server"

json

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

4.3 Claude Code

bash

claude mcp add firecrawl -- npx -y firecrawl-mcp
# 然后设置环境变量 FIRECRAWL_API_KEY

或在项目的 .mcp.json 中：

json

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

4.4 VS Code

在 .vscode/mcp.json 中：

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

4.5 本地 Streamable HTTP 模式

如果 Agent 不支持 stdio 但支持 HTTP MCP：

bash

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

MCP URL：http://localhost:3000/mcp

4.6 自托管 Firecrawl 实例

bash

env FIRECRAWL_API_URL=https://firecrawl.your-domain.com FIRECRAWL_API_KEY=your-key npx -y firecrawl-mcp

五、可选环境变量

变量名	默认值	说明
`FIRECRAWL_RETRY_MAX_ATTEMPTS`	3	最大重试次数
`FIRECRAWL_RETRY_INITIAL_DELAY`	1000	首次重试延迟(ms)
`FIRECRAWL_RETRY_MAX_DELAY`	10000	最大重试延迟(ms)
`FIRECRAWL_RETRY_BACKOFF_FACTOR`	2	指数退避乘数
`FIRECRAWL_CREDIT_WARNING_THRESHOLD`	1000	额度警告阈值
`FIRECRAWL_CREDIT_CRITICAL_THRESHOLD`	100	额度严重阈值
`FIRECRAWL_NO_SEARCH_FEEDBACK`	(未设置)	设为 `1` 禁用搜索反馈工具
`HTTP_STREAMABLE_SERVER`	false	设为 `true` 启用 HTTP 模式
`FIRECRAWL_API_URL`	(Cloud)	自托管实例 URL

六、安装后的工具列表（已验证）

成功连接后，MCP Server 提供以下工具：

工具名	功能
`firecrawl_scrape`	抓取单个 URL 的内容
`firecrawl_batch_scrape`	批量抓取多个 URL
`firecrawl_check_batch_status`	检查批量任务状态
`firecrawl_map`	发现网站上的所有 URL
`firecrawl_search`	Web 搜索
`firecrawl_search_feedback`	搜索结果反馈（可退 1 credit）
`firecrawl_crawl`	爬取整个网站
`firecrawl_check_crawl_status`	检查爬取任务状态
`firecrawl_extract`	LLM 驱动的结构化数据提取
`firecrawl_agent`	自主网络研究 Agent
`firecrawl_agent_status`	检查 Agent 任务状态
`firecrawl_interact`	与已抓取页面交互（点击、填表）
`firecrawl_interact_stop`	停止交互会话
`firecrawl_monitor_create`	创建页面变更监控
`firecrawl_monitor_list`	列出所有监控
`firecrawl_monitor_get`	获取单个监控详情
`firecrawl_monitor_update`	更新监控配置
`firecrawl_monitor_delete`	删除监控
`firecrawl_monitor_run`	立即触发监控检查
`firecrawl_monitor_checks`	列出监控历史
`firecrawl_monitor_check`	获取单次检查详情

七、已知坑和注意事项汇总

7.1 Cloud MCP 的 SSE 响应格式

Firecrawl Cloud MCP 返回的是 SSE（Server-Sent Events）格式，不是纯 JSON。响应格式为：

event: message
id: <uuid>
data: <JSON payload>

MCP Client 必须支持解析 SSE 格式，否则无法读取响应。

7.2 initialize 必须 Accept SSE

详见 3.3 节。HTTP 请求头 Accept 必须包含 text/event-stream。

7.3 搜索后的反馈调用

firecrawl_search 返回的结果包含一个 id 字段。使用完搜索结果后，应该调用 firecrawl_search_feedback 并传入该 id，可以退回 1 credit（搜索消耗 2 credit）。这是实际可验证的行为。

7.4 tools/list 可能超时

通过 HTTP 直接调用 tools/list 方法可能在某些网络环境下超时（本环境实测超时）。建议通过 MCP Client 框架的内置工具发现机制来获取工具列表，而非手动 HTTP 调用。

7.5 npm 包名 vs GitHub 仓库名

npm 包名： firecrawl-mcp（安装命令：npx -y firecrawl-mcp）
GitHub 仓库： firecrawl/firecrawl-mcp-server（https://github.com/firecrawl/firecrawl-mcp-server）
两者名字不同，不要混淆

7.6 ⚠️ 踩坑：Hermes Agent 写错配置路径

问题： Agent 安装 Firecrawl MCP 时，没有先确认自己是哪个 profile，想当然写到了错误的位置。

正确逻辑：先确认，再写入

bash

# 第一步：确认当前 profile
echo $HERMES_HOME

根据输出判断：

`$HERMES_HOME` 输出	含义	必需配置路径	可选 `.env` 路径
空或 `~/.hermes`	default profile	`~/.hermes/config.yaml`	`~/.hermes/.env`
`/home/xxx/.hermes/profiles/xxx-agent`	非 default profile	`$HERMES_HOME/config.yaml`	`$HERMES_HOME/.env`

错误表现：

非 default profile 的 Agent 把配置写到了 ~/.hermes/（全局目录）
导致 MCP Server 配置不生效，工具列表中看不到 firecrawl

正确操作：

bash

# 1. 确认当前 profile
echo $HERMES_HOME

# 2. 根据输出决定写入位置
#    - 如果输出为空或 ~/.hermes → config.yaml 写到 ~/.hermes/
#    - 如果输出是 ~/.hermes/profiles/xxx → config.yaml 写到那个目录
#
# 注意：当前 Firecrawl Cloud MCP 连接必需的是 config.yaml 中的 URL；
# .env 中的 FIRECRAWL_API_KEY 不是此连接的必需项。

根本原因： Agent 没有先检查 $HERMES_HOME，直接假设自己是 default profile。

八、快速验证清单

安装完成后，按以下步骤验证：

bash

# 1. 检查 MCP Server 是否可达（Cloud 模式）
curl -s -X POST https://mcp.firecrawl.dev/fc-YOUR_KEY/v2/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}'
# 预期：返回包含 "firecrawl-fastmcp" 的 SSE 响应

# 2. 检查 Agent 平台是否识别工具
hermes tools list | grep firecrawl   # Hermes Agent
# 预期：firecrawl  all tools enabled

# 3. 执行一次简单搜索验证功能
# 在 Agent 中调用 firecrawl_search，query: "test"

九、信息来源

本环境实际运行的 Hermes Agent 配置（config.yaml / $HERMES_HOME profile 路径）
通过临时禁用 .env 中 FIRECRAWL_API_KEY 验证：Firecrawl Cloud MCP 仍可通过 mcp_servers.firecrawl.url 成功发现工具
通过 curl 对 mcp.firecrawl.dev 的实际 HTTP 请求验证
Firecrawl MCP Server 官方 GitHub 仓库 README（https://github.com/firecrawl/firecrawl-mcp-server）
npm registry 中的 firecrawl-mcp 包信息
Hermes hermes tools list 实际输出

Firecrawl MCP 安装指南（面向 AI Agent） ​

一、前置条件 ​

二、两种接入模式 ​

模式 A：Firecrawl Cloud MCP（Streamable HTTP 远程托管） ​

模式 B：本地 stdio 模式（npx 启动） ​

三、模式 A 配置详情（已验证） ​

3.1 Hermes Agent 中的配置 ​

3.2 用 curl 手动验证 MCP 连接 ​

3.3 ⚠️ 踩坑：Accept Header 必须包含 text/event-stream ​

3.4 ⚠️ 踩坑：URL 路径中的 API Key ​

四、模式 B 配置详情（已从官方文档验证） ​

4.1 Claude Desktop ​

4.2 Cursor ​

4.3 Claude Code ​

4.4 VS Code ​

4.5 本地 Streamable HTTP 模式 ​

4.6 自托管 Firecrawl 实例 ​

五、可选环境变量 ​

六、安装后的工具列表（已验证） ​

七、已知坑和注意事项汇总 ​

7.1 Cloud MCP 的 SSE 响应格式 ​

7.2 initialize 必须 Accept SSE ​

7.3 搜索后的反馈调用 ​

7.4 tools/list 可能超时 ​

7.5 npm 包名 vs GitHub 仓库名 ​

7.6 ⚠️ 踩坑：Hermes Agent 写错配置路径 ​

八、快速验证清单 ​

九、信息来源 ​

Firecrawl MCP 安装指南（面向 AI Agent）

一、前置条件

二、两种接入模式

模式 A：Firecrawl Cloud MCP（Streamable HTTP 远程托管）

模式 B：本地 stdio 模式（npx 启动）

三、模式 A 配置详情（已验证）

3.1 Hermes Agent 中的配置

3.2 用 curl 手动验证 MCP 连接

3.3 ⚠️ 踩坑：Accept Header 必须包含 text/event-stream

3.4 ⚠️ 踩坑：URL 路径中的 API Key

四、模式 B 配置详情（已从官方文档验证）

4.1 Claude Desktop

4.2 Cursor

4.3 Claude Code

4.4 VS Code

4.5 本地 Streamable HTTP 模式

4.6 自托管 Firecrawl 实例

五、可选环境变量

六、安装后的工具列表（已验证）

七、已知坑和注意事项汇总

7.1 Cloud MCP 的 SSE 响应格式

7.2 initialize 必须 Accept SSE

7.3 搜索后的反馈调用

7.4 tools/list 可能超时

7.5 npm 包名 vs GitHub 仓库名

7.6 ⚠️ 踩坑：Hermes Agent 写错配置路径

八、快速验证清单

九、信息来源