Doramagic.ai
English

Doramagic 项目包 · 项目说明书

firecrawl-mcp-server 项目

Firecrawl 的 MCP 服务器，支持网页搜索、爬取、页面交互、批处理以及基于 LLM 的内容分析，兼容云端和自托管实例。

Overview, Architecture and Installation

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 npm 直接运行

继续阅读本节完整说明和来源证据。

章节 关键环境变量

继续阅读本节完整说明和来源证据。

章节 从源码构建

继续阅读本节完整说明和来源证据。

概览、架构与安装

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

项目定位与适用场景

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

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

架构与组件关系

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

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）；同时 Docker 容器默认仅监听 IPv6 ::1，与 NGINX 转发到 IPv4 回环冲突，需注意绑定配置（issue #251）。

传输模式与注册元数据

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

传输客户端类型典型问题
stdioClaude Desktop、CursorPython/Windows 客户端在 1.7.0 前会挂起（CHANGELOG 1.7.0）；3.18.0+ 鉴权回归
Streamable HTTPn8n、Web 集成路径与版本必须严格匹配（issue #64）

安装与配置

npm 直接运行

最简安装方式是通过 npx：

FIRECRAWL_API_KEY=YOUR_KEY npx -y firecrawl-mcp

或全局安装后运行 firecrawl-mcp 可执行文件（package.json:6-10）。

关键环境变量

  • FIRECRAWL_API_KEY：云端 API 密钥；自托管实例若设置了自定义 FIRECRAWL_BASE_URL 可不提供（v3.2.0 修复后行为，详见 release 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）。
  • FIRECRAWL_CREDIT_WARNING_THRESHOLD、FIRECRAWL_CREDIT_CRITICAL_THRESHOLD：积分监控阈值。

从源码构建

克隆仓库后执行：

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

build 脚本会自动 chmod 755 输出文件，便于直接调用（package.json:14-24）。

自托管注意事项

使用自托管 Firecrawl 时，需确保 FIRECRAWL_BASE_URL 指向实例地址；v3.2.0 后已修复"自定义 URL 仍要求 API Key"的问题，但 issue #126 报告部分场景仍异常，建议同时设置 FIRECRAWL_API_KEY 或升级到最新 3.20.x 修复版。社区也反馈 server.json 中 packages[0].version（3.20.2）与 npm 实际版本（3.21.0）存在差异（issue #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 等已知问题）

来源：https://github.com/firecrawl/firecrawl-mcp-server / 项目说明书

Available Tools Reference and Selection Guide

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与工具分类

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-50scrape 返回空内容时定位正确页面已经知道目标 URLurl, 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
  • Self-hosted Firecrawl Setup
  • Search & Feedback Workflow
  • Monitor Lifecycle
  • Research Tools (Experimental)

来源：https://github.com/firecrawl/firecrawl-mcp-server / 项目说明书

Configuration, Authentication and Versioning

Firecrawl MCP Server 是一个 Model Context Protocol（MCP）服务器，为 LLM 客户端（如 Cursor、Claude Desktop）提供网页抓取、搜索与交互能力。配置、认证与版本管理是部署和运行该服务器的核心三要素：配置决定了运行时传输方式与日志行为；认证决定了如何对 Firecrawl API（云端或自托管实例）进行身份验证...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 运行时脚本与构建

继续阅读本节完整说明和来源证据。

章节 传输模式

继续阅读本节完整说明和来源证据。

章节 关键环境变量

继续阅读本节完整说明和来源证据。

概述

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 与 CHANGELOG.md 记录，常用环境变量包括：

环境变量用途
FIRECRAWL_API_KEYFirecrawl 云端 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。
  • 自托管仍要求 API Key（v3.2.0 修复后）：部分用户在 v3.2.0 修复后仍遇到自托管实例强制要求 API Key 的问题。资料来源：Issue #126。
  • Docker 容器 IPv6 监听问题：Docker 镜像仅监听 IPv6 ::1，而 NGINX 反向代理转发至 IPv4 127.0.0.1，导致连接失败。资料来源：Issue #251。

日志与传输感知

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

版本管理（Versioning）

双版本架构

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

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 默认值0172800000ms（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。
  4. 遇到 stdio Unauthorized 时，检查当前是否处于 v3.18.0+ 回归版本范围。

另请参阅

资料来源：package.json:18-30。

Deployment, Docker and Common Failure Modes

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

章节 相关页面

继续阅读本节完整说明和来源证据。

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

继续阅读本节完整说明和来源证据。

章节 2. Docker 容器仅监听 IPv6 ::1

继续阅读本节完整说明和来源证据。

章节 3. 自托管仍要求 API Key

继续阅读本节完整说明和来源证据。

部署、Docker 与常见故障模式

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

部署模式总览

Firecrawl MCP Server 在 package.json 中声明了 bin.firecrawl-mcp 入口，并通过若干 npm script 区分启动方式：

启动方式命令用途
本地 stdionpm 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 StreamableHTTP_STREAMABLE_SERVER=true npm start启用新版流式 HTTP 传输（V2 起推荐）

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

Docker 容器化

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

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

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

常见故障模式

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

社区报告（issue #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 反映：容器内 MCP 进程默认绑定 IPv6 ::1，而宿主侧 NGINX 监听 IPv4 127.0.0.1，两者地址族不同导致 localhost 连接失败。规避方式包括：以 --network host 启动容器，或让 NGINX 同时监听 [::1]:port。

3. 自托管仍要求 API Key

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

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

issue #64 中用户使用 n8n 接入自托管 Firecrawl 时收到 404。原因是请求路径未携带版本前缀。VERSIONING.md 明确 V2 消息端点为 /:apiKey/v2/messages，客户端必须按版本对齐路径。

5. Windows 11 下连接失败

issue #36 报告在 Windows 11 上出现 Client Closed or Failed to create。CHANGELOG.md 中 v1.7.0 已修复 stdio 日志重定向到 stderr 的问题（解决 Python 客户端挂起），Windows 用户应优先升级到最新版本再排查。

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

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

调试与排障建议

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

See Also

来源：https://github.com/firecrawl/firecrawl-mcp-server / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Using n8n to connect to firecrawl-mcp-server throws a 404 error

可能增加新用户试用和生产接入成本。

high 失败模式：security_permissions: 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

medium 失败模式：installation: 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)

medium 失败模式：installation: stdio: every tool call returns "Unauthorized" in 3.18.0+ with FIRECRAWL_API_KEY (regression f...

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)

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录