fetchmcp

fetchmcp

可直接替代官方 fetch MCP，真正适用于现代网页。

官方 fetch MCP 无法处理大量使用 JavaScript 的网页，会将输出截断至 5,000 个字符，而且存在未修补的 SSRF 漏洞。fetchmcp 可从任意 URL 返回整洁、适合大模型使用的 Markdown——需要时渲染 JavaScript，无需付费代理即可通过基础机器人防护；网页被拦截时也会如实告知，而不会编造内容。运行 npx 即可。

// Replace the official fetch server with this — one line in your MCP config:
"fetchmcp": { "command": "npx", "args": ["-y", "@labtoolsstudio/fetchmcp"] }

 

为什么要切换

	官方 fetch	fetchmcp
JavaScript 网页	❌ 返回空内容／无法处理	✅ 在真实浏览器中自动渲染
输出长度	✂️ 截断至 5,000 个字符	✅ 返回完整网页，支持分页
机器人防护（403／Cloudflare）	❌ 静默失败	✅ 可通过中等强度的防护，无需付费代理
被拦截的网页	❌ 将 CAPTCHA 当作“内容”返回	✅ 返回明确的类型化错误，绝不伪造内容
SSRF 安全性	❌ CVE-2025-65513（CVSS 9.3）	✅ 默认拒绝私有／元数据 IP
费用	免费	免费、可自托管，$0

安装

将其添加到 MCP 客户端配置（claude_desktop_config.json、Cursor mcp.json、Cline 等）：

{
  "mcpServers": {
    "fetchmcp": {
      "command": "npx",
      "args": ["-y", "@labtoolsstudio/fetchmcp"]
    }
  }
}

安装过程很轻量——不会预先下载浏览器，静态读取（fetch → Readability → Markdown）可立即使用。首次遇到确实需要 JavaScript 的网页时，fetchmcp 会自动下载一次隐身版 Chromium（约 150 MB），然后进行渲染——仍然无需配置。若要在安装时预先下载，请设置 FETCHMCP_PREINSTALL_BROWSER=1。若要仅使用静态模式且永不下载，请设置 FETCHMCP_SKIP_BROWSER_DOWNLOAD=1（此时 JavaScript 网页会返回明确的 needs_js）。

工具

read_url

将任意网页抓取为整洁的 Markdown。

参数	类型	描述
url	string	要抓取的 URL（http/https）
render	boolean	JavaScript 渲染：true = 始终渲染，false = 从不渲染，省略 = 自动渲染（仅适用于空的 SPA 外壳）
raw	boolean	返回原始 HTML，而不是 Markdown
headers	object	额外请求标头，例如 {"Authorization": "Bearer …", "Cookie": "…"}
max_length	integer	限制返回的字符数（0 = 不限，默认值）
start_index	integer	长网页分页读取的起始偏移量

read_docs

使用相同的引擎，针对文档进行了优化：移除导航侧边栏、页眉和页脚，让 API 文档和指南以整洁的参考文本形式返回。接受 url、render、headers、max_length、start_index。

明确的状态

fetchmcp 绝不会将机器人拦截页、错误页面或截断的外壳伪装成真实内容返回。无法读取网页时，它会说明原因，并返回类型化状态：blocked（机器人防护，含供应商名称）、blocked_ssrf、needs_js、http_error、timeout、network_error、unsupported_content 或 empty。

配置（环境变量）

变量	默认值	含义
FETCHMCP_TIMEOUT_MS	30000	每个请求的超时时间
FETCHMCP_MAX_RETRIES	2	网络错误 / 429 / 503 时的重试次数（采用退避策略并遵循 Retry-After）
FETCHMCP_ALLOW_PRIVATE_IP	未设置	设为 1 以允许访问私有 / localhost IP（可信内网文档）
FETCHMCP_FLARESOLVERR_URL	未设置	自托管 FlareSolverr 端点，用于应对更棘手的挑战
FETCHMCP_SKIP_BROWSER_DOWNLOAD	未设置	设为 1 以仅使用静态模式：绝不下载 Chromium；JS 页面会返回 needs_js
FETCHMCP_PREINSTALL_BROWSER	未设置	设为 1，在安装时下载 Chromium，而不是首次使用 JS 时下载

开发与测试

npm install          # installs deps (Chromium downloads on first JS use)
npm run build        # compile TypeScript to dist/
npm test             # unit tests (block detection, SSRF) — no network
npm run test:e2e     # live end-to-end suite against real sites

# Poke at any tool/URL by hand — no need to write a script:
node test/probe.mjs read_url  https://example.com
node test/probe.mjs read_url  https://some-spa.example.com --render
node test/probe.mjs read_docs https://docs.python.org/3/library/json.html
node test/probe.mjs read_url  https://api.example.com --header "Authorization=Bearer x" --max-length 500
node test/probe.mjs read_url  https://example.com --full     # print the whole response

test/probe.mjs --help 的语义记录在该文件顶部。

工作原理

分为三个层级，仅在需要时逐级升级：

1. 静态模式 — 普通 fetch → Readability → Markdown。适用于大多数页面的快速路径。
2. 浏览器模式 — 当静态 HTML 是空的 SPA 外壳、机器人拦截页，或返回 403/429/503 时，按需使用 patchright（隐身版 Chromium）。
3. FlareSolverr（可选）— 仅当你已配置端点时使用，用于处理浏览器无法通过的挑战。

Star 历史

如果 fetchmcp 帮你避免了又一次 fetch 返回空内容的窘境，点个星标可以帮助其他人发现它。

许可证

MIT — 参见 LICENSE。