Firecrawl MCP 代理（Vercel）

把 Firecrawl 官方 MCP 服务变成你自己的：客户端只持有你自己的代理 Key，Firecrawl 的 Key 永远留在服务端。 25 个工具、工具描述、serverInfo、连接语义全部与官方一致，对 MCP 客户端来说它就是 Firecrawl MCP。

• 🔑 只需要 2 个环境变量：PROXY_API_KEY + FIRECRAWL_API_KEY

• 🧰 满血功能：透明转发官方 MCP，官方新增工具/修复自动生效（当前 = 25 个工具全量）

• 🔁 两种传输：Streamable HTTP（/mcp，推荐）+ 旧版 SSE（/sse、/messages；上游侧几乎接不通，见端点一览）

• 💳 额外余额接口：GET /credits 查询剩余额度

• 🪶 零依赖、零构建配置：从 GitHub 导入即可部署，无需选框架、无需构建命令

一键部署

按钮指向的就是下面这条链接，已预填仓库、项目名与两个环境变量的名字，点开即用（打开页面不需要登录，但真正创建项目需要 Vercel 账号，并授权它读取该私有仓库）：

https://vercel.com/new/clone?repository-url=https://github.com/fskanokano/firecrawl-mcp-proxy&project-name=firecrawl-mcp-proxy&repository-name=firecrawl-mcp-proxy&env=PROXY_API_KEY,FIRECRAWL_API_KEY

两点开箱前就该知道（都不是占位符，不需要你替换任何东西）：

• 本仓库目前是 private（https://github.com/fskanokano/firecrawl-mcp-proxy）。第一次用上面的链接时，Vercel 会要求你授权它访问 GitHub（安装 GitHub App / 授予该仓库权限）——private 仓库必须走这一步才能被导入；未登录或未授权的情况下，GitHub 对 private 仓库一律返回 404 而不是 403，这是 GitHub 的行为，不是链接写错了。若你想在自己的 GitHub 账号下部署，先按下文 clone 再推到你自己的仓库，把链接里的 repository-url 换成你的地址。

• 两个 Key 的值不在 URL 里，而是在导入时填入。 为了避免把秘密写进 URL、浏览器历史和 Vercel 日志，上面只预填了变量名 PROXY_API_KEY、FIRECRAWL_API_KEY；值请在导入表单的 Environment Variables 里粘贴，再点 Deploy。

把仓库拿到本地（private 仓库需要 GitHub 登录凭据，或先用 gh auth login 授权）：

git clone https://github.com/fskanokano/firecrawl-mcp-proxy.git
cd firecrawl-mcp-proxy

手动导入同样简单：

1. Vercel → Add New… → Project → Import Git Repository，选中 fskanokano/firecrawl-mcp-proxy（private 仓库首次需要授权 GitHub 访问；想换成你自己的账号，先 clone 再推过去即可）。

2. Framework Preset 保持 Other，Build Command / Output Directory / Install Command 全部留空（本仓库不需要构建）。

3. 在 Environment Variables 里填两个变量（值从下面的表格里取），然后 Deploy。

4. 部署完成后访问 https://<你的项目>.vercel.app/mcp（不带任何 Key）：返回 401 {"success":false,"error":"missing_api_key",…} 就说明代理已经跑起来了；若返回 500 proxy_misconfigured，则是环境变量没配或名字拼错。

下文所有 https://<你的项目>.vercel.app/… 里的 <你的项目> 是你自己的 Vercel 项目名，部署之后才存在，因此无法预先写成可点的链接；本文档里其余写出的 URL 都是可直接打开的真实地址（需要登录的会注明）。

两个环境变量

就这两个。上游地址固定指向官方（https://mcp.firecrawl.dev 与 https://api.firecrawl.dev），没有别的开关。这两个是服务端接口而不是给人用的页面：直接 GET https://api.firecrawl.dev 会返回 {"message":"Firecrawl API",…}，在浏览器里打开 https://mcp.firecrawl.dev 会跳到官方 MCP 文档页——都属正常，不代表代理出问题。

Related MCP server: shantycrawl-mcp

客户端配置

把 <你的项目> 换成你的 Vercel 域名，<PROXY_API_KEY> 换成代理 Key。四种传 Key 的方式都支持： Authorization: Bearer、x-api-key、x-firecrawl-api-key、URL 里的 ?apiKey=。

通用（推荐：Streamable HTTP）

{
  "mcpServers": {
    "firecrawl": {
      "type": "http",
      "url": "https://<你的项目>.vercel.app/mcp",
      "headers": { "Authorization": "Bearer <PROXY_API_KEY>" }
    }
  }
}

Cursor / VS Code / Claude Code 等

• Cursor：Settings → MCP → Add new MCP server，Type 选 http（或 streamable-http），URL 填 https://<你的项目>.vercel.app/mcp，Headers 加 Authorization: Bearer <PROXY_API_KEY>。

• Claude Code：claude mcp add --transport http firecrawl https://<你的项目>.vercel.app/mcp --header "Authorization: Bearer <PROXY_API_KEY>"

• VS Code / 其他 IDE：在 mcp.json 里等价写成 {"type":"http","url":"…/mcp","headers":{"Authorization":"Bearer …"}}。

老客户端（只支持 SSE）

{
  "mcpServers": {
    "firecrawl": { "url": "https://<你的项目>.vercel.app/sse?apiKey=<PROXY_API_KEY>" }
  }
}

代理会重写 SSE 的 endpoint 事件，让后续消息 POST 回你自己的域名（/messages?sessionId=…），无需额外配置——这点用官方 MCP SDK（@modelcontextprotocol/sdk@1.30.0 的 SSEClientTransport）验证过：客户端确实按重写后的地址回 POST，并把 ?apiKey= 原样带上。 注意：官方这套旧版传输依赖上游的会话亲和性，实际几乎接不通。成对运行的 8 组（直连官方 /sse 与经本代理各一次）两侧都是 0/8，均返回上游 400 "No active transport"；21 次经代理的尝试中只有 1 次完成握手。失败原因是上游侧实例没有持有该 session，与本代理无关。能用 Streamable HTTP 的客户端请用 /mcp。

纯 HTTP 调用（脚本 / n8n / 自研 Agent）

curl -sS https://<你的项目>.vercel.app/mcp \
  -H "Authorization: Bearer $PROXY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

端点一览

下表的「实测」列写明该端点在开发环境中被真实调用过的方式；上游不支持的方法本代理会原样透传上游的状态码，不会假装成功。

未提供（有意为之）：官方的 /v2/mcp-search 只读搜索专线是 OAuth-only 面，实测用 fc- Key 直连也会被拒（401 invalid_token / OAuth access token required），因此在「只用两个环境变量 + API Key」的前提上它永远不可用，本代理不暴露该路径；/v2/mcp-oauth 同理不暴露（本代理不做 OAuth 登录流程）。

余额查询接口

curl -sS https://<你的项目>.vercel.app/credits \
  -H "Authorization: Bearer $PROXY_API_KEY"

返回 Firecrawl 官方结构（原样透传），并附加一个 checkedAt 时间戳：

{
  "success": true,
  "data": {
    "remainingCredits": 1000,
    "planCredits": 500000,
    "billingPeriodStart": "2026-09-01T00:00:00Z",
    "billingPeriodEnd": "2026-09-30T23:59:59Z"
  },
  "checkedAt": "2026-09-14T12:00:00.000Z"
}

Firecrawl 拒绝该 Key 时，会原样返回 401 {"success":false,"error":"Unauthorized: Invalid token"} —— 这也是判断 FIRECRAWL_API_KEY 是否有效的最快方式。

支持的工具（25 个）

scrape、map、search、search_feedback、feedback、crawl、check_crawl_status、parse、agent、agent_status、interact、interact_stop、developer_search、research_search_papers、research_inspect_paper、research_related_papers、research_read_paper、monitor_create / list / get / update / run / delete / checks / check。

这份清单直接来自官方 MCP，官方增删工具这里会同步变化，无需升级本仓库。

部署限制与注意事项

• 函数最长执行时间（vercel.json 已设为 maxDuration: 300）

  • Hobby / Pro 默认上限都是 300 秒；Pro / Enterprise 可提高到 800 秒（vercel.json 里把 api/*.js 的 maxDuration 改成 800），付费团队在 beta 中最高 1800 秒。

  • 超大 crawl 可能超过 300 秒，此时改用 firecrawl_map + 单页 firecrawl_scrape，或用 firecrawl_crawl 拿到 id 后用 firecrawl_check_crawl_status 续查，不必让一个请求一直挂着。

• 无状态：上游会话语义（含 mcp-session-id）原样透传，但本代理不保存任何状态，因此不依赖 KV、数据库或 Redis。

• 请求体上限 4 MB：Vercel 本身限制 4.5 MB，代理在 4 MB 处直接返回 413。

• /parse 的本地文件流程：官方托管 MCP 不支持读取客户端本地文件，需按其两段式上传流程（filePath → 上传 → uploadRef）操作，与本代理无关。

• 区域与网络：默认部署在 Vercel 默认区域，若主要调用方在亚洲，可在项目设置里把 Functions 区域调到更近的节点。

本地开发

npm install          # 仅安装 typescript / @types/node（仅用于类型检查，运行时零依赖）

npm test             # 52 个单元测试（node:test，覆盖鉴权、头部隔离、转发、错误映射、SSE 重写与并发隔离、余额接口）
npm run typecheck    # 用 JSDoc 类型做静态检查（tsc --noEmit，不产出文件）

# 端到端冒烟：本地起服务 + 真实调用官方上游
PROXY_API_KEY=dev-key FIRECRAWL_API_KEY=fc-xxxxx node scripts/smoke.js

scripts/smoke.js 会真的连官方上游，检查：鉴权拦截、serverInfo 伪装、工具数量、SSE 重写、余额接口状态码。 不设 FIRECRAWL_API_KEY 也能跑（用占位 Key，工具调用会按预期被上游拒绝）。

为什么用 JavaScript 而不是 TypeScript

Vercel 的 /api 函数构建器是逐文件转译 + 按依赖追踪，不会打包，.ts 的相对导入在部署后经常变成 ERR_MODULE_NOT_FOUND。 本仓库用原生 ESM + 精确文件名（./lib/relay.js 就是磁盘上的文件），本地跑的和线上跑的是同一份代码；类型安全通过 JSDoc + tsc --checkJs 保证。 （该结论已在本地用 @vercel/node 真实构建器验证：4 个函数全部构建为 Lambda，lib/*.js 均被正确追踪进产物。）

目录结构

api/                  Vercel Functions（每个文件只做一件事：把请求交给对应端点）
lib/config.js         环境变量 → 配置；一个请求的依赖（配置 + fetch）
lib/auth.js           代理 Key 的提取；返回“哪个凭证通过了”的恒定时间比对
lib/gate.js           请求准入：配置、方法、凭证，并把通过校验的凭证交给端点
lib/client-headers.js 客户端响应头策略的唯一归属：转发哪些头、浏览器可读哪些头、CORS/no-store
lib/upstream.js       上游请求的唯一归属：凭证呈现、头部白名单、请求体上限与读取、发送
lib/relay.js          回包的唯一归属：不缓冲地流式回传上游响应
lib/forward.js        转发路径的唯一归属：发送 → 归类失败（超时/不可达）→ 回传
lib/http.js           本代理自己发明的响应形状（JSON 错误包、预检、405/413/500/502/504）
lib/sse-rewrite.js    旧版 SSE 的 endpoint 事件重写
lib/endpoints/        mcp.js / sse.js / messages.js / credits.js
tests/                node:test 单元测试
scripts/smoke.js      端到端冒烟脚本
vercel.json           路由别名 + 函数时长

安全建议

• 客户端只拿到 PROXY_API_KEY；Firecrawl Key 只存在于 Vercel 环境变量里，任何响应体和错误信息都不会泄露它（已有测试覆盖）。

• 代理会剥离客户端携带的 authorization / x-api-key / x-firecrawl-api-key / cookie，只放行 MCP 必需的少数头部（content-type、accept、mcp-session-id、mcp-protocol-version、last-event-id），避免凭证被转交或伪造；客户端的 user-agent / accept-language 不会转发给 Firecrawl。

• 怀疑泄露就轮换 PROXY_API_KEY（改环境变量后 Redeploy 即可），不需要重新生成客户端配置里的 URL。

• 用 ?apiKey= 传 Key 会出现在 URL 和访问日志里，仅在客户端确实无法设置请求头时使用；优先用 Authorization 头。

常见问题

免责声明

本项目是自托管的代理，与 Firecrawl 官方无隶属关系，仅按官方公开的 MCP/REST 接口转发请求；Firecrawl 及相关标识归其所有者。请遵守 Firecrawl 的服务条款与配额限制。

MIT License.