# https://github.com/firecrawl/firecrawl-mcp-server 项目说明书

生成时间：2026-06-21 08:51:13 UTC

## 目录

- [Overview, Architecture and Installation](#page-1)
- [Available Tools Reference and Selection Guide](#page-2)
- [Configuration, Authentication and Versioning](#page-3)
- [Deployment, Docker and Common Failure Modes](#page-4)

<a id='page-1'></a>

## Overview, Architecture and Installation

### 相关页面

相关主题：[Configuration, Authentication and Versioning](#page-3), [Deployment, Docker and Common Failure Modes](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md)
- [package.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)
- [server.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/server.json)
- [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)
- [src/research.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/research.ts)
- [src/monitor.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/monitor.ts)
- [CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)
</details>

# 概览、架构与安装

Firecrawl MCP Server 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的服务器，将 Firecrawl 的网页搜索、抓取、解析、监控与研究能力暴露为标准化的工具接口，使 LLM 客户端（如 Claude Desktop、Cursor 等）能够以协议化方式调用外部 Web 数据。其 npm 包名为 `firecrawl-mcp`，CLI 入口为 `firecrawl-mcp`，MCP 注册名为 `io.github.firecrawl/firecrawl-mcp-server`（[package.json:1-12](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)）。

## 项目定位与适用场景

服务器以"薄封装"方式提供 Firecrawl v2 API 的主要端点，包括抓取（scrape）、搜索（search）、站点地图（map）、批量处理、结构化抽取（extract）以及异步研究代理（agent）。除了基础抓取，还包括以下三类高阶能力：

- **本地文件解析**：`firecrawl_parse` 支持 PDF、HTML、DOCX、XLSX 等本地文件（[src/index.ts:parse section](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)）。
- **学术与代码研究**：`firecrawl_research_arxiv` 与 `firecrawl_research_github` 通过 `/v2/search/research/*` 端点检索 arXiv 论文与 GitHub issue/PR 历史（[src/research.ts:1-30](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/research.ts)）。
- **变化监控**：`firecrawl_monitor_*` 工具提供基于目标（goal）的有意义变化判定，输出 `judgment.meaningful` 与 `meaningfulChanges`（[src/monitor.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/monitor.ts)）。

## 架构与组件关系

服务器在进程启动时读取环境变量，根据 `CLOUD_SERVICE` 与 `FIRECRAWL_API_KEY` 等变量选择云端或自托管模式，并通过 `@mendable/firecrawl-js` SDK 建立 HTTP 客户端。每个工具以 `server.addTool` 形式注册，Zod schema 定义参数，执行时通过 `getClient(session)` 获取会话级客户端并调用对应端点（[src/index.ts:scrape tool](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)）。

```mermaid
flowchart LR
  A[MCP 客户端<br/>Claude/Cursor/n8n] -- JSON-RPC --> B[Firecrawl MCP Server]
  B -- HTTP --> C[Firecrawl 云端 API]
  B -- HTTP --> D[自托管 Firecrawl 实例]
  B -.stdio 模式.-> A
  B -.streamable HTTP 模式.-> A
  B --> E[工具集合:<br/>scrape/search/map/extract<br/>agent/parse/monitor/research]
  E --> F[Firecrawl v2 REST API]
```

值得注意的是，stdio 传输在 3.18.0+ 版本曾出现 "Unauthorized" 回归（[issue #246](https://github.com/firecrawl/firecrawl-mcp-server/issues/246)）；同时 Docker 容器默认仅监听 IPv6 `::1`，与 NGINX 转发到 IPv4 回环冲突，需注意绑定配置（[issue #251](https://github.com/firecrawl/firecrawl-mcp-server/issues/251)）。

## 传输模式与注册元数据

服务器注册清单在 `server.json` 中声明，stdio 为默认传输类型，并要求可选的 `FIRECRAWL_API_KEY` 环境变量（[server.json:14-25](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/server.json)）。v2.0.0 起新增 Streamable HTTP 传输（[CHANGELOG](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)），使 n8n 等 HTTP 客户端可直接连接。

| 传输 | 客户端类型 | 典型问题 |
|------|------------|----------|
| stdio | Claude Desktop、Cursor | Python/Windows 客户端在 1.7.0 前会挂起（[CHANGELOG 1.7.0](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)）；3.18.0+ 鉴权回归 |
| Streamable HTTP | n8n、Web 集成 | 路径与版本必须严格匹配（[issue #64](https://github.com/firecrawl/firecrawl-mcp-server/issues/64)） |

## 安装与配置

### npm 直接运行

最简安装方式是通过 npx：

```bash
FIRECRAWL_API_KEY=YOUR_KEY npx -y firecrawl-mcp
```

或全局安装后运行 `firecrawl-mcp` 可执行文件（[package.json:6-10](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)）。

### 关键环境变量

- `FIRECRAWL_API_KEY`：云端 API 密钥；自托管实例若设置了自定义 `FIRECRAWL_BASE_URL` 可不提供（v3.2.0 修复后行为，详见 [release v3.2.0](https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v3.2.0)）。
- `CLOUD_SERVICE=true`：启用云端服务模式（对应 `npm run start:cloud`）。
- `FIRECRAWL_RETRY_MAX_ATTEMPTS`、`FIRECRAWL_RETRY_INITIAL_DELAY`、`FIRECRAWL_RETRY_MAX_DELAY`、`FIRECRAWL_RETRY_BACKOFF_FACTOR`：重试策略（[CHANGELOG 1.2.4](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)）。
- `FIRECRAWL_CREDIT_WARNING_THRESHOLD`、`FIRECRAWL_CREDIT_CRITICAL_THRESHOLD`：积分监控阈值。

### 从源码构建

克隆仓库后执行：

```bash
npm install
npm run build      # tsc 编译并设置 dist/index.js 可执行权限
npm start          # 启动 stdio 服务器
```

`build` 脚本会自动 `chmod 755` 输出文件，便于直接调用（[package.json:14-24](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)）。

### 自托管注意事项

使用自托管 Firecrawl 时，需确保 `FIRECRAWL_BASE_URL` 指向实例地址；v3.2.0 后已修复"自定义 URL 仍要求 API Key"的问题，但 [issue #126](https://github.com/firecrawl/firecrawl-mcp-server/issues/126) 报告部分场景仍异常，建议同时设置 `FIRECRAWL_API_KEY` 或升级到最新 3.20.x 修复版。社区也反馈 `server.json` 中 `packages[0].version`（3.20.2）与 npm 实际版本（3.21.0）存在差异（[issue #255](https://github.com/firecrawl/firecrawl-mcp-server/issues/255)），发布标签自 v3.2.0 后未更新，发布流程可能为手动。

## See Also

- Tools Reference（工具参考）：scrape / search / map / extract / agent / parse / monitor / research
- Configuration Reference（环境变量与重试策略详解）
- Troubleshooting（stdio 鉴权、IPv6 绑定、self-hosted API Key 等已知问题）

---

<a id='page-2'></a>

## Available Tools Reference and Selection Guide

### 相关页面

相关主题：[Overview, Architecture and Installation](#page-1), [Configuration, Authentication and Versioning](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)
- [src/monitor.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/monitor.ts)
- [src/research.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/research.ts)
- [src/types/fastmcp.d.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/types/fastmcp.d.ts)
- [src/legacy/index.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/legacy/index.md)
</details>

# Available Tools Reference and Selection Guide

## 概述与工具分类

`firecrawl-mcp-server` 通过 Model Context Protocol（MCP）暴露一组围绕 Firecrawl v2 API 的网络工具，覆盖**抓取、解析、映射、提取、搜索、异步代理、监控与实验性研究**等场景。所有工具均通过 `server.AddTool` 注册到 FastMCP 框架，并按调用语义分类 `readOnlyHint`、`openWorldHint` 与 `destructiveHint` 注解 [src/index.ts:1-50]()。

工具按职能可划分为四组：

- **内容获取**：`firecrawl_scrape`、`firecrawl_parse`、`firecrawl_map`
- **结构化提取与异步研究**：`firecrawl_extract`、`firecrawl_agent` + `firecrawl_agent_status`
- **监控**：`firecrawl_monitor_*` 系列（详见 [src/monitor.ts]()）
- **实验性研究**：`firecrawl_research_arxiv`、`firecrawl_research_github`（详见 [src/research.ts]()）

## 核心工具对照表

下表汇总各工具的用途、最佳适用场景与常见误区，可作为选型速查：

| 工具 | 主要用途 | 最佳适用场景 | 不推荐场景 | 关键参数 |
|------|----------|---------------|-------------|----------|
| `firecrawl_scrape` | 抓取单个 URL 并返回指定格式 [src/index.ts:1-50]() | 已知 URL，需要 Markdown / JSON / branding | 未知 URL 列表 | `formats`, `onlyMainContent`, `lockdown`, `redactPII` |
| `firecrawl_parse` | 解析**本地文件**（HTML、PDF、Office、RTF）[src/index.ts:1-50]() | 本地 PDF/HTML 提取 | 远程 URL（应改用 scrape） | `filePath`, `parsers`, `pdfOptions.maxPages` |
| `firecrawl_map` | 列举站点全部索引 URL [src/index.ts:1-50]() | scrape 返回空内容时定位正确页面 | 已经知道目标 URL | `url`, `search` |
| `firecrawl_extract` | 多 URL 结构化抽取 [src/index.ts:1-50]() | 跨页面抓取同一类字段 | 单页抽取（用 scrape） | `urls`, `prompt`, `schema` |
| `firecrawl_agent` + `_status` | 异步自主代理研究 [src/index.ts:1-50]() | 未知 URL 的多源研究；JS 重 SPA | 已知 URL 单页抽取 | `prompt`, `urls`, `schema` |
| `firecrawl_research_arxiv` | 检索 arXiv 论文 [src/research.ts]() | 学术研究背景检索 | 非学术主题 | `query`, `k`, `categories`, `dateFrom/dateTo` |
| `firecrawl_research_github` | 检索 GitHub issue/PR/readme [src/research.ts]() | 在开源仓库内寻找已知 bug/特性 | 私有仓库 | `query`, `k` |
| `firecrawl_monitor_*` | 创建与查询页面变更监控 [src/monitor.ts]() | 价格/政策跟踪；SLA 监控 | 单次快照 | `url`/`pages`, `goal`, `schema` |

## 异步工作流与监控工具

`firecrawl_agent` 采用**异步作业模式**：调用立即返回 jobId，调用方需通过 `firecrawl_agent_status` 以 15–30 秒间隔轮询，持续至少 2–3 分钟，复杂任务可达 5 分钟以上 [src/index.ts:1-50]()。该机制适合多源研究，但不应用于已知 URL 的单页提取。

`firecrawl_monitor_create` / `firecrawl_monitor_checks` 用于持续跟踪页面变更，结果中包含 `judgment`、`meaningfulChanges` 与 `isMeaningful` 字段，便于按目标（goal）过滤噪声 [src/monitor.ts]()。变更摘要优先使用 `diff.json` 路径（如 `plans[0].price`）而非原始 markdown diff，更紧凑且贴合监控目标 [src/monitor.ts]()。

## 实验性研究工具

`src/research.ts` 提供两个 thin MCP 封装，调用 `/v2/search/research/*` 端点（arXiv 与 GitHub 历史/READMEs）。由于当前安装的 `@mendable/firecrawl-js` 早于官方 `research` 客户端，这些工具通过 SDK 的 `client.http.get` 直接访问 HTTP 层，复用其鉴权与重试逻辑 [src/research.ts]()。结果格式经过截断与去噪：论文摘要、作者列表与机构均设有字符上限，GitHub 匹配内容上限为 1200 字符，以避免超出 MCP 输出 token 限制 [src/research.ts]()。

## 工具选择最佳实践与常见陷阱

1. **先 map 后 agent**：当 `firecrawl_scrape` 返回空内容或 SPA 不完整时，应优先用 `firecrawl_map` 加 `search` 参数定位真实 URL，再回退到 `firecrawl_agent` [src/index.ts:1-50]()。
2. **格式选择**：需要特定字段时使用 `formats: ["json"]` 加 `jsonOptions.schema`；阅读整篇文章时才用 markdown 默认 [src/index.ts:1-50]()。
3. **缓存加速**：`maxAge` 参数可使抓取提速约 500%；`lockdown: true` 用于隔离环境，禁止任何出站请求，缓存缺失则报错并按 5 credits 计费 [src/index.ts:1-50]()。
4. **文档与代码一致性**：社区已报告部分文档仍引用 `firecrawl_batch_scrape`，但当前 MCP 已不再注册该工具；同时 `server.AddTool` 的描述中曾残留 `batch_scrape` 引用，会导致模型行为不一致（#130、#113）。
5. **`firecrawl_search` 的 `sources` 字段**：OpenAPI 规范要求其为含 `type` 的对象数组，错误写法会触发 422 错误（#127）。提交搜索反馈时需在 ~2 分钟窗口内，遵循 `good/partial/bad` 各自的必填字段约束 [src/index.ts:1-50]()。
6. **自托管模式**：`FIRECRAWL_API_KEY` 在 v3.2.0 后当设置了自定义 `FIRECRAWL_BASE_URL` 时不再强制，但 #126 报告显示部分部署仍存在回归，需结合版本与配置复核。
7. **stdio 鉴权回归**：自 3.18.0 起出现过 stdio 传输下所有调用返回 `Unauthorized` 的问题（#246），升级前请确认补丁版本或暂时回退到 3.17.x。

## See Also

- [Configuration & Transports](configuration.md)
- [Self-hosted Firecrawl Setup](self-hosted-setup.md)
- [Search & Feedback Workflow](search-feedback.md)
- [Monitor Lifecycle](monitor-lifecycle.md)
- [Research Tools (Experimental)](research-tools.md)

---

<a id='page-3'></a>

## Configuration, Authentication and Versioning

### 相关页面

相关主题：[Overview, Architecture and Installation](#page-1), [Deployment, Docker and Common Failure Modes](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)
- [src/research.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/research.ts)
- [src/monitor.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/monitor.ts)
- [package.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)
- [VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)
- [CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)
</details>

# Configuration, Authentication and Versioning

## 概述

Firecrawl MCP Server 是一个 Model Context Protocol（MCP）服务器，为 LLM 客户端（如 Cursor、Claude Desktop）提供网页抓取、搜索与交互能力。配置、认证与版本管理是部署和运行该服务器的核心三要素：配置决定了运行时传输方式与日志行为；认证决定了如何对 Firecrawl API（云端或自托管实例）进行身份验证；版本管理则确保新旧 Firecrawl SDK 的兼容性。资料来源：[package.json:1-10]()。

服务器使用 `@mendable/firecrawl-js` SDK 调用底层 API，并通过 `firecrawl-fastmcp` 框架注册工具。配置主要由环境变量驱动，认证基于 `FIRECRAWL_API_KEY`（云端必填，自托管可选），版本则通过端点路径区分 V1 与 V2 实现。资料来源：[src/index.ts:1-50]()。

## 配置（Configuration）

### 运行时脚本与构建

`package.json` 定义了多个 npm 脚本用于不同部署场景：

| 脚本 | 说明 |
|------|------|
| `npm start` | 启动本地 V2 服务器（默认 stdio 传输） |
| `npm run start:cloud` | 设置 `CLOUD_SERVICE=true` 启动云端版本化端点 |
| `npm run build` | 编译 TypeScript 并设置 `dist/index.js` 可执行权限 |

资料来源：[package.json:18-30]()。

### 传输模式

服务器支持三种传输模式，可通过环境变量切换：

- **stdio**（默认）：用于本地 MCP 客户端，通过标准输入输出通信。
- **SSE_LOCAL=true**：启用本地 SSE 传输。
- **HTTP_STREAMABLE_SERVER=true**：启用 HTTP Streamable 传输。

资料来源：[VERSIONING.md:60-70]()。

### 关键环境变量

根据 [VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) 与 [CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) 记录，常用环境变量包括：

| 环境变量 | 用途 |
|----------|------|
| `FIRECRAWL_API_KEY` | Firecrawl 云端 API 密钥（云端必填） |
| `FIRECRAWL_BASE_URL` | 自托管实例的 API 地址 |
| `CLOUD_SERVICE` | 是否启用云端版本化端点 |
| `SSE_LOCAL` | 是否启用本地 SSE 传输 |
| `HTTP_STREAMABLE_SERVER` | 是否启用 HTTP Streamable 传输 |
| `FIRECRAWL_RETRY_MAX_ATTEMPTS` | 重试最大次数 |
| `FIRECRAWL_CREDIT_WARNING_THRESHOLD` | 余额告警阈值 |

资料来源：[CHANGELOG.md:50-65]()。

## 认证（Authentication）

### API Key 处理

服务器通过 `getClient(session)` 函数获取或创建 Firecrawl SDK 客户端实例。当使用云端服务时，`FIRECRAWL_API_KEY` 为必需项；自托管实例在 v3.2.0 修复后，若设置了自定义 `FIRECRAWL_BASE_URL` 则不再强制要求 API Key。资料来源：[VERSIONING.md:30-45]()。

### 已知认证回归问题

社区报告了若干与认证相关的故障模式，需特别留意：

- **stdio 传输回归（v3.18.0+）**：自 2026-05-28 的 3.18.0→3.19.1 版本发布后，使用 stdio 传输时即使设置了 `FIRECRAWL_API_KEY`，所有工具调用仍会返回 `Unauthorized: API key is required when not using a self-hosted instance` 错误。这是相对 v3.17.0 的回退问题。资料来源：[Issue #246](https://github.com/firecrawl/firecrawl-mcp-server/issues/246)。
- **自托管仍要求 API Key（v3.2.0 修复后）**：部分用户在 v3.2.0 修复后仍遇到自托管实例强制要求 API Key 的问题。资料来源：[Issue #126](https://github.com/firecrawl/firecrawl-mcp-server/issues/126)。
- **Docker 容器 IPv6 监听问题**：Docker 镜像仅监听 IPv6 `::1`，而 NGINX 反向代理转发至 IPv4 `127.0.0.1`，导致连接失败。资料来源：[Issue #251](https://github.com/firecrawl/firecrawl-mcp-server/issues/251)。

### 日志与传输感知

为解决 Python 客户端在 stdio 传输下的挂起问题，v1.7.0 引入了传输感知的日志机制——stdio 模式下日志输出至 stderr，避免与协议消息混用。资料来源：[CHANGELOG.md:40-48]()。

## 版本管理（Versioning）

### 双版本架构

服务器支持 V1（Legacy）与 V2（Current）两套端点，通过 URL 路径区分：

```mermaid
graph LR
  A[CLOUD_SERVICE=true] --> B{API 版本}
  B -->|V1 Legacy| C[/:apiKey/sse<br/>:apiKey/messages]
  B -->|V2 Current| D[/:apiKey/v2/sse<br/>:apiKey/v2/messages]
  A --> E[/health 健康检查]
  F[Local stdio/SSE/HTTP] --> D
```

资料来源：[VERSIONING.md:15-25]()。

### V1 与 V2 差异

| 维度 | V1 (Legacy) | V2 (Current) |
|------|-------------|--------------|
| SDK 版本 | `@mendable/firecrawl-js` 1.29.3 | `@mendable/firecrawl-js` 3.1.0+ |
| 工具调用 | `client.scrapeUrl()` 等 | 现代 REST 端点 |
| `maxAge` 默认值 | 0 | 172800000ms（48 小时） |
| `onlyMainContent` | 需手动指定 | 默认 `true` |
| 工具集 | 含 `firecrawl_deep_research`、`firecrawl_generate_llmstxt` | 已移除，引入 JSON 提取与多源搜索 |

资料来源：[VERSIONING.md:35-55]()。

### 迁移建议

从 V1 迁移至 V2 时需：

1. 更新端点 URL，添加 `/v2/` 路径前缀。
2. 移除对 `firecrawl_deep_research` 与 `firecrawl_generate_llmstxt` 的调用。
3. 适配新的 JSON 提取 schema 格式。
4. 利用 V2 默认的 `maxAge` 缓存与 `onlyMainContent` 行为降低成本。

资料来源：[VERSIONING.md:55-65]()。

## 故障排查指引

综合社区报告的高频问题，建议按以下顺序排查：

1. 确认 `FIRECRAWL_API_KEY` 是否正确设置（云端）或 `FIRECRAWL_BASE_URL` 是否指向有效的自托管实例。
2. 若使用 Docker，验证容器是否绑定至 `0.0.0.0` 而非仅 `::1`。
3. 若使用 n8n 等外部 MCP 客户端，确认 URL 路径正确（如 `/v2/sse` 与 `/v2/messages`）。资料来源：[Issue #64](https://github.com/firecrawl/firecrawl-mcp-server/issues/64)。
4. 遇到 stdio `Unauthorized` 时，检查当前是否处于 v3.18.0+ 回归版本范围。

## 另请参阅

- 工具集与 API 用法：参见 [`src/index.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)
- 研究型工具实现：参见 [`src/research.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/research.ts)
- 监控工具语义：参见 [`src/monitor.ts`](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/monitor.ts)
- 版本变更历史：参见 [CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) 与 [VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)

---

<a id='page-4'></a>

## Deployment, Docker and Common Failure Modes

### 相关页面

相关主题：[Overview, Architecture and Installation](#page-1), [Configuration, Authentication and Versioning](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [Dockerfile](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/Dockerfile)
- [Dockerfile.service](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/Dockerfile.service)
- [docker/entrypoint.sh](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/docker/entrypoint.sh)
- [docker/nginx.conf](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/docker/nginx.conf)
- [server.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/server.json)
- [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)
- [package.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)
- [VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)
- [CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)
</details>

# 部署、Docker 与常见故障模式

本页介绍 firecrawl-mcp-server 的部署形态、Docker 容器化方式以及社区中常见的故障模式与规避方法。

## 部署模式总览

Firecrawl MCP Server 在 [package.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json) 中声明了 `bin.firecrawl-mcp` 入口，并通过若干 npm script 区分启动方式：

| 启动方式 | 命令 | 用途 |
| --- | --- | --- |
| 本地 stdio | `npm start` | 由 Claude Desktop、Cursor 等客户端直接 fork 进程调用 |
| 云端版本化服务 | `npm run start:cloud` | 启用 `CLOUD_SERVICE=true`，暴露 `/v2/sse`、`/v2/messages` |
| SSE 本地 | `SSE_LOCAL=true npm start` | 本地启用 SSE 传输，便于 HTTP 客户端连接 |
| HTTP Streamable | `HTTP_STREAMABLE_SERVER=true npm start` | 启用新版流式 HTTP 传输（V2 起推荐） |

[VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) 详细说明了 V1 与 V2 两套端点并存的结构：云端模式下分别监听 `/:apiKey/sse`（V1 兼容）与 `/:apiKey/v2/sse`（V2 默认），本地模式默认走 V2 实现。健康检查端点固定为 `/health`。[package.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json) 中 `engines.node` 要求 `>=18.0.0`，容器构建需以此为基础镜像约束。

## Docker 容器化

仓库提供两套 Dockerfile，分别面向两种使用场景：

- [Dockerfile](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/Dockerfile) —— 用于 MCP stdio 客户端（如 Claude Desktop）以 stdio 协议调用，启动后立即进入 MCP 握手。
- [Dockerfile.service](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/Dockerfile.service) —— 将 server 作为长期运行的 HTTP/SSE 服务暴露，依赖 [docker/entrypoint.sh](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/docker/entrypoint.sh) 拉起 Node 进程。

[docker/nginx.conf](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/docker/nginx.conf) 在反向代理场景下将公网流量转发到容器内的 MCP 服务。`server.json` 描述了容器镜像在 MCP 注册中心所需的元数据（如启动命令、传输协议、所需环境变量），便于通过 Smithery、CodeGuilds 等渠道一键安装。客户端部署时常通过环境变量 `FIRECRAWL_API_KEY`（云端）或 `FIRECRAWL_API_URL`（自托管）注入鉴权信息，配置方式见 [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts) 中的 `getClient` 工厂。

## 常见故障模式

### 1. stdio 鉴权失败（3.18.0+ 回归）

社区报告（[issue #246](https://github.com/firecrawl/firecrawl-mcp-server/issues/246)）：自 3.18.0 版本起，通过 stdio 传输调用任何工具都会返回 `Unauthorized: API key is required when not using a self-hosted instance`。根因是 `FIRECRAWL_API_KEY` 环境变量在新版本中未正确传递至会话上下文。临时规避方法是回退到 3.17.0，或在 stdio 模式下显式将密钥写入客户端配置。

### 2. Docker 容器仅监听 IPv6 ::1

[issue #251](https://github.com/firecrawl/firecrawl-mcp-server/issues/251) 反映：容器内 MCP 进程默认绑定 IPv6 `::1`，而宿主侧 NGINX 监听 IPv4 `127.0.0.1`，两者地址族不同导致 `localhost` 连接失败。规避方式包括：以 `--network host` 启动容器，或让 NGINX 同时监听 `[::1]:port`。

### 3. 自托管仍要求 API Key

[v3.2.0 release](https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v3.2.0) 修复了"自定义 baseURL 时仍强制 API Key"的问题，但 [issue #126](https://github.com/firecrawl/firecrawl-mcp-server/issues/126) 显示仍有用户复现该问题。建议确认 `FIRECRAWL_API_URL` 已指向自托管实例，且未被云端默认值覆盖；同时检查 [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts) 中的客户端构造分支是否走到了自托管路径。

### 4. n8n / 第三方客户端返回 404

[issue #64](https://github.com/firecrawl/firecrawl-mcp-server/issues/64) 中用户使用 n8n 接入自托管 Firecrawl 时收到 404。原因是请求路径未携带版本前缀。[VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) 明确 V2 消息端点为 `/:apiKey/v2/messages`，客户端必须按版本对齐路径。

### 5. Windows 11 下连接失败

[issue #36](https://github.com/firecrawl/firecrawl-mcp-server/issues/36) 报告在 Windows 11 上出现 `Client Closed or Failed to create`。[CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) 中 v1.7.0 已修复 stdio 日志重定向到 stderr 的问题（解决 Python 客户端挂起），Windows 用户应优先升级到最新版本再排查。

### 6. 版本号缺失导致发布漂移

[issue #255](https://github.com/firecrawl/firecrawl-mcp-server/issues/255) 指出当前 `package.json` 已升至 `3.20.2`，但仓库自 v3.2.0 后再无 Git tag 与 GitHub Release，NPM 发布可能为人工流程。[CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) 中可见 3.19.0 等条目已记录 monitor、batch scrape 等新功能，但未在 Releases 页面同步——下游在锁版本时需谨慎。

## 调试与排障建议

1. 借助 [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts) 中的 `log.info` 输出确认 transport 模式（stdio/SSE/HTTP streamable），区分客户端连接层与服务调用层错误。
2. 使用 `/health` 端点（见 [VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)）快速确认服务存活。
3. 容器化部署中显式声明网络模式与监听地址，避免 IPv4/IPv6 不匹配。
4. 自托管场景同时设置 `FIRECRAWL_API_URL` 与 `FIRECRAWL_API_KEY`（后者可为占位值），触发代码中的自托管分支。

## See Also

- [README — Quick Start](https://github.com/firecrawl/firecrawl-mcp-server#readme)
- [VERSIONING.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md)
- [CHANGELOG.md](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md)
- [package.json](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/package.json)
- [src/index.ts](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/src/index.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：firecrawl/firecrawl-mcp-server

摘要：发现 29 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Using n8n to connect to firecrawl-mcp-server throws a 404 error。

## 1. 安装坑 · 来源证据：Using n8n to connect to firecrawl-mcp-server throws a 404 error

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Using n8n to connect to firecrawl-mcp-server throws a 404 error
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/firecrawl/firecrawl-mcp-server/issues/64 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 失败模式：security_permissions: Proposal: Free AI Agent identity verification for Firecrawl MCP

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Proposal: Free AI Agent identity verification for Firecrawl MCP
- 对用户的影响：Developers may expose sensitive permissions or credentials: Proposal: Free AI Agent identity verification for Firecrawl MCP
- 证据：failure_mode_cluster:github_issue | https://github.com/firecrawl/firecrawl-mcp-server/issues/243 | Proposal: Free AI Agent identity verification for Firecrawl MCP

## 3. 安装坑 · 失败模式：installation: Project is on 3.20.2 (2026-06-01) but has no tags or releases since 3.2.0 (2025-09-26)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Project is on 3.20.2 (2026-06-01) but has no tags or releases since 3.2.0 (2025-09-26)
- 对用户的影响：Developers may fail before the first successful local run: Project is on 3.20.2 (2026-06-01) but has no tags or releases since 3.2.0 (2025-09-26)
- 证据：failure_mode_cluster:github_issue | https://github.com/firecrawl/firecrawl-mcp-server/issues/255 | Project is on 3.20.2 (2026-06-01) but has no tags or releases since 3.2.0 (2025-09-26)

## 4. 安装坑 · 失败模式：installation: stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression f...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression from 3.17.0)
- 对用户的影响：Developers may fail before the first successful local run: stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression from 3.17.0)
- 证据：failure_mode_cluster:github_issue | https://github.com/firecrawl/firecrawl-mcp-server/issues/246 | stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression from 3.17.0)

## 5. 安装坑 · 失败模式：installation: v1.12.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.12.0
- 对用户的影响：Upgrade or migration may change expected behavior: v1.12.0
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v1.12.0 | v1.12.0

## 6. 安装坑 · 来源证据：Your project is now listed on CodeGuilds

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your project is now listed on CodeGuilds
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/firecrawl/firecrawl-mcp-server/issues/271 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 7. 配置坑 · 失败模式：configuration: v1.2.3: Optimize Batch Processing

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.2.3: Optimize Batch Processing
- 对用户的影响：Upgrade or migration may change expected behavior: v1.2.3: Optimize Batch Processing
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v1.2.3 | v1.2.3: Optimize Batch Processing

## 8. 配置坑 · 失败模式：configuration: v1.2.4: Configurable Settings & Enhanced Documentation

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.2.4: Configurable Settings & Enhanced Documentation
- 对用户的影响：Upgrade or migration may change expected behavior: v1.2.4: Configurable Settings & Enhanced Documentation
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v1.2.4 | v1.2.4: Configurable Settings & Enhanced Documentation

## 9. 配置坑 · 来源证据：MCP tool descriptions teach models the wrong calling convention, causing systematic tool-call failures

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：MCP tool descriptions teach models the wrong calling convention, causing systematic tool-call failures
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/firecrawl/firecrawl-mcp-server/issues/279 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://www.npmjs.com/package/firecrawl-mcp | README/documentation is current enough for a first validation pass.

## 11. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://www.npmjs.com/package/firecrawl-mcp | matched external service / cloud / webhook / database keyword

## 12. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/firecrawl-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://www.npmjs.com/package/firecrawl-mcp | no_demo; severity=medium

## 14. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://www.npmjs.com/package/firecrawl-mcp | no_demo; severity=medium

## 15. 安全/权限坑 · 来源证据：Proposal: Free AI Agent identity verification for Firecrawl MCP

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proposal: Free AI Agent identity verification for Firecrawl MCP
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/firecrawl/firecrawl-mcp-server/issues/243 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 16. 安全/权限坑 · 来源证据：[Regulatory Signals] firecrawl-mcp is listed on the MCP Trust Registry — claim it

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Regulatory Signals] firecrawl-mcp is listed on the MCP Trust Registry — claim it
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/firecrawl/firecrawl-mcp-server/issues/274 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression from 3.17.0)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression from 3.17.0)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/firecrawl/firecrawl-mcp-server/issues/246 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 18. 能力坑 · 失败模式：capability: Provided docker container cannot be connected to, because MCP server only listens to ipv6 ::1...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Provided docker container cannot be connected to, because MCP server only listens to ipv6 ::1 while NGINX proxies traffic to ipv4 loopback
- 对用户的影响：Developers may hit a documented source-backed failure mode: Provided docker container cannot be connected to, because MCP server only listens to ipv6 ::1 while NGINX proxies traffic to ipv4 loopback
- 证据：failure_mode_cluster:github_issue | https://github.com/firecrawl/firecrawl-mcp-server/issues/251 | Provided docker container cannot be connected to, because MCP server only listens to ipv6 ::1 while NGINX proxies traffic to ipv4 loopback

## 19. 能力坑 · 失败模式：capability: Your project is now listed on CodeGuilds

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Your project is now listed on CodeGuilds
- 对用户的影响：Developers may hit a documented source-backed failure mode: Your project is now listed on CodeGuilds
- 证据：failure_mode_cluster:github_issue | https://github.com/firecrawl/firecrawl-mcp-server/issues/254 | Your project is now listed on CodeGuilds

## 20. 能力坑 · 失败模式：conceptual: Using n8n to connect to firecrawl-mcp-server throws a 404 error

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Using n8n to connect to firecrawl-mcp-server throws a 404 error
- 对用户的影响：Developers may hit a documented source-backed failure mode: Using n8n to connect to firecrawl-mcp-server throws a 404 error
- 证据：failure_mode_cluster:github_issue | https://github.com/firecrawl/firecrawl-mcp-server/issues/64 | Using n8n to connect to firecrawl-mcp-server throws a 404 error

## 21. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/firecrawl-mcp | issue_or_pr_quality=unknown

## 22. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/firecrawl-mcp | release_recency=unknown

## 23. 维护坑 · 失败模式：maintenance: Added Deep Research (Alpha)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Added Deep Research (Alpha)
- 对用户的影响：Upgrade or migration may change expected behavior: Added Deep Research (Alpha)
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v1.4.1 | Added Deep Research (Alpha)

## 24. 维护坑 · 失败模式：maintenance: Added llms.txt generator

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Added llms.txt generator
- 对用户的影响：Upgrade or migration may change expected behavior: Added llms.txt generator
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v1.7.2 | Added llms.txt generator

## 25. 维护坑 · 失败模式：maintenance: Official Release - v1.3.3

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Official Release - v1.3.3
- 对用户的影响：Upgrade or migration may change expected behavior: Official Release - v1.3.3
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v.1.3.3 | Official Release - v1.3.3

## 26. 维护坑 · 失败模式：maintenance: v2.0.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2.0.0
- 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v2.0.0 | v2.0.0

## 27. 维护坑 · 失败模式：maintenance: v3.0.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v3.0.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.0.0
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v3.0.0 | v3.0.0

## 28. 维护坑 · 失败模式：maintenance: v3.2.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v3.2.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.2.0
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v3.2.0 | v3.2.0

## 29. 维护坑 · 失败模式：maintenance: v3.2.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v3.2.1
- 对用户的影响：Upgrade or migration may change expected behavior: v3.2.1
- 证据：failure_mode_cluster:github_release | https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v3.2.1 | v3.2.1

<!-- canonical_name: firecrawl/firecrawl-mcp-server; human_manual_source: deepwiki_human_wiki -->