Webfetch Mcp

webfetch-mcp

一个本地 Python MCP 服务，可将 AI 助手内置的 WebFetch 工具替换为完全可配置的 HTTP 客户端——支持按域名设置请求头、重试、代理、超时、输出格式、机器人拦截检测和提示词注入净化，除了注册此服务之外，无需改动助手配置中的任何内容。

为什么需要

大多数 AI 助手（Claude Code、Cursor、Continue、Zed 等）内置的 WebFetch 工具发送请求时不会添加自定义请求头，因此会被机器人防护系统（Akamai、Cloudflare、付费墙等）拦截，也无法通过需要域名专属令牌的 API 进行身份验证。

此服务可直接替代原有工具：它向任何兼容 MCP 的 AI 助手提供相同的 fetch 工具，但会根据目标域名自动为每个外发请求添加适当的请求头、格式和重试策略，无需每次都手动配置请求头。

---

功能

功能	说明
按域名设置请求头	每个域名可使用不同的身份验证请求头；全局 * 作为回退配置
单次调用请求头	客户端（或你）可以为单个请求注入额外的请求头
YAML 配置	通过一个易读的文件统一控制请求头、超时、重试、代理和输出格式
可配置超时	按域名设置请求超时（默认 30 s）
退避重试	HTTP 5xx 或网络错误时自动重试，并采用指数退避
按域名设置代理	可为不同域名的流量分别配置代理
输出格式	raw、markdown、trafilatura（主要内容）、json（美化打印）、lighthtml（精简 HTML）
JSON 自动检测	Content-Type 为 application/json 的响应会自动美化打印
元数据提取	通过 trafilatura 提取标题、作者、日期和来源（可按域名选择启用）
机器人拦截检测	检测 Cloudflare / CAPTCHA 拦截；可选使用 Chrome User-Agent 重试
提示词注入净化	扫描抓取的内容，检测注入模式；支持 flag 或 strip 模式
CSS 选择器提取	在格式转换前提取指定的 HTML 元素；可按域名或单次调用配置
重定向跟踪	可选记录并在摘要中显示完整的重定向链
响应断言	assert_status / assert_contains 不匹配时会报错，适用于 CI/CD 冒烟测试
请求头注入防护	验证请求头中是否含有控制字符（\r、\n、NUL）
响应截断	使用 max_bytes 限制响应大小，避免占满助手的上下文窗口
详细响应摘要	每个响应都包含结构化摘要（状态、耗时毫秒数、注入的请求头、格式等）
JavaScript 渲染（Playwright）	使用无头 Chromium 渲染 JavaScript 密集型 SPA，然后提取内容；可全局、按域名或按次调用配置
lighthtml 输出格式	去除 <style>、<script>（JSON-LD 除外）、注释和所有标签属性，返回精简的纯 HTML 结构
TLS 指纹模拟（curl-cffi）	重现真实浏览器的 TLS ClientHello/JA3 和 HTTP/2 指纹，以绕过可在请求头层级以下进行指纹识别的 CDN 机器人检测；可全局、按域名或按次调用配置

---

要求

• Python 3.10+
• 任意兼容 MCP 的 AI 助手（Claude Code、Cursor、Continue、Zed 等）

---

快速开始

git clone https://github.com/simonediroma/webfetch_mcp.git
cd webfetch_mcp

# Mac / Linux
python -m venv .venv && .venv/bin/pip install -r requirements.txt
# Windows
python -m venv .venv && .venv\Scripts\pip install -r requirements.txt

cp webfetch.yaml.example webfetch.yaml   # then edit with your tokens

然后在 AI 助手配置中注册此服务并重启即可。

---

安装

git clone https://github.com/simonediroma/webfetch_mcp.git
cd webfetch_mcp

python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt

# Mac / Linux
.venv/bin/pip install -r requirements.txt

requirements.txt 会安装：

mcp[cli]>=1.0.0
httpx>=0.27.0
python-dotenv>=1.0.0
markdownify>=0.12.0
trafilatura>=1.12.0
pyyaml>=6.0
beautifulsoup4>=4.12.0

可选 — JS 渲染需要 Playwright：

pip install playwright && playwright install chromium

---

配置

有两种配置服务的方式。推荐使用 YAML——它支持所有选项。旧版环境变量方式仍适用于简单场景。

选项 A — YAML 配置文件（推荐）

复制示例文件并进行编辑：

cp webfetch.yaml.example webfetch.yaml

指定服务使用该文件：

# In your shell profile, or in the MCP server env block (see Registration below)
export WEBFETCH_CONFIG=/absolute/path/to/webfetch.yaml

YAML 完整参考

# Global defaults — applied to every request unless overridden
global:
  headers:
    User-Agent: "MyBot/1.0"
  output_format: raw       # raw | markdown | trafilatura | json | lighthtml
  timeout: 30              # seconds
  retry:
    attempts: 1            # 1 = no retry
    backoff: 2.0           # exponential multiplier (1s → 2s → 4s …)
  proxy: null              # e.g. "http://proxy.corp:8080"
  extract_metadata: false  # true = prepend title/author/date to content
  sanitize_content: false  # false | "flag" | "strip"
  bot_block_detection: false  # false | "report" | "retry"
  css_selector: null       # CSS selector to extract element(s) before format conversion
  render_js: false           # true = render JS via headless Chromium (requires playwright)
  impersonate: null          # e.g. "chrome131" = impersonate a browser's TLS/HTTP2 fingerprint
                              # (requires curl-cffi); loses to render_js when both are set

# Per-domain overrides — only the fields you list are overridden
domains:
  example.com:
    headers:
      X-Akamai-Token: "your-token-here"
    output_format: trafilatura
    timeout: 60
    retry:
      attempts: 3
      backoff: 2.0

  news-site.com:
    output_format: markdown
    bot_block_detection: retry   # auto-retry with Chrome UA if blocked
    css_selector: "article.main-content"  # extract only the article body

  internal.corp:
    proxy: "http://proxy.corp:8080"
    headers:
      Authorization: "Bearer my-internal-token"

  api.example.com:
    output_format: json
    timeout: 10
    retry:
      attempts: 5
      backoff: 1.5

  fingerprinted-cdn.com:
    impersonate: chrome131   # bypasses TLS/JA3-fingerprint bot detection
    output_format: trafilatura

域名匹配使用后缀规则：example.com 会匹配 example.com 和 www.example.com。如果匹配到多个域名，则采用最具体（键最长）的规则。始终先应用全局设置，然后再由越来越具体的域名规则覆盖。

---

选项 B — 环境变量（旧版）

复制 .env.example 并填写相应值：

cp .env.example .env

WEBFETCH_HEADERS — 按域名配置的请求标头（单行 JSON）：

WEBFETCH_HEADERS={"*": {"User-Agent": "MyBot/1.0"}, "example.com": {"X-Auth-Token": "your-token"}}

WEBFETCH_OUTPUT — 按域名配置的输出格式（单行 JSON）：

WEBFETCH_OUTPUT={"*": "raw", "example.com": "trafilatura", "news.com": "markdown"}

WEBFETCH_SELECTORS — 按域名配置的 CSS 选择器（单行 JSON）：

WEBFETCH_SELECTORS={"example.com": "article.main-content", "news.com": "div#article-body"}

设置 WEBFETCH_CONFIG 后，上述环境变量将完全被忽略。

---

注册到你的 AI 助手

大多数 AI 助手都在 JSON 设置文件中使用 mcpServers 块。所有助手的格式相同，只有文件位置不同。

Claude Code

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "webfetch": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "WEBFETCH_CONFIG": "/absolute/path/to/webfetch.yaml"
      }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）：

{
  "mcpServers": {
    "webfetch": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "WEBFETCH_CONFIG": "/absolute/path/to/webfetch.yaml"
      }
    }
  }
}

Claude Desktop（Mac / Windows）

在 Mac 上添加到 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上添加到 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "webfetch": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "WEBFETCH_CONFIG": "/absolute/path/to/webfetch.yaml"
      }
    }
  }
}

**Windows：**将 .venv\Scripts\python.exe 用作 command 值。

其他助手（Continue、Zed 等）

请查阅你的助手的 MCP 文档，了解确切的配置文件位置。服务块相同，只有文件路径不同。

**Windows：**使用 .venv\Scripts\python.exe，而不是 .venv/bin/python

保存后重启客户端。该工具注册为 mcp__webfetch__fetch。

---

确认服务已启动

注册并重启客户端后，确认工具已加载：

• Claude Code：在聊天中运行 /mcp——webfetch 应显示为 connected 状态，并将 fetch 列为可用工具。
• Cursor：打开 Settings → MCP，确认 webfetch 出现在活动服务列表中。
• 其他客户端：在设置中查找 MCP 工具面板或服务列表。

如果服务未显示，请检查：

1. 配置中的 Python 路径和 server.py 路径是否为正确的绝对路径。
2. 虚拟环境是否已安装所有依赖（pip install -r requirements.txt）。
3. YAML/env 配置是否存在错误——在终端中直接运行 python server.py，查看 stderr 中的启动错误。

---

强制客户端使用 webfetch，而不是内置工具

大多数 AI 助手同时提供内置 WebFetch 和已注册的 MCP 工具。若要确保始终优先使用 mcp__webfetch__fetch：

Claude Code

将以下内容添加到项目的 CLAUDE.md（或添加到 ~/.claude/CLAUDE.md，以全局应用于所有项目）：

Always use the `mcp__webfetch__fetch` tool for all HTTP requests and web browsing.
Do not use the built-in WebFetch tool.

或者，在 ~/.claude/settings.json 中添加 systemPrompt 条目：

{
  "systemPrompt": "Always use mcp__webfetch__fetch for all web requests. Do not use the built-in WebFetch tool.",
  "mcpServers": { "...": "..." }
}

其他 AI 助手

请查阅你的助手文档，了解如何设置系统提示词或自定义指令。需要添加的指令如下：

所有网页请求都使用 mcp__webfetch__fetch，而不是任何内置的抓取或浏览器工具。

---

端到端示例

安装并注册后，打开你的 AI 助手并试试：

“获取 https://example.com 并返回主要内容”

助手会自动调用 mcp__webfetch__fetch，并应用你为该域名配置的请求头和输出格式。你会看到类似这样的响应：

--- Request Summary ---
URL:              https://example.com
Method:           GET
Injected headers: User-Agent
Status:           200 OK
Elapsed:          312ms
Output format:    trafilatura
---

[Extracted article content here]

如果你配置了域名专属的身份验证请求头，摘要行 Injected headers 会列出这些请求头，确认它们已发送。无需额外提示；每次向该域名发出请求时，都会自动应用配置。

---

工具 API

除 url 外，所有参数均为可选。

参数	类型	默认值	描述
url	str	—	要获取的 URL
method	str	"GET"	HTTP 方法（GET、POST、PUT、DELETE、…）
body	str | None	None	POST/PUT 请求正文
extra_headers	dict | None	None	单次调用的请求头，会与域名请求头合并
extract_text	bool	False	移除 HTML 标签并返回纯文本（旧版参数；会覆盖 output_format）
max_bytes	int	0	将响应截断为 N 个字符（0 = 不限）
follow_redirects	bool	True	跟随 HTTP 重定向
output_format	str | None	None	单次调用的格式覆盖项："raw"、"markdown"、"trafilatura"、"json"、"lighthtml"
css_selector	str | None	None	转换格式前，用 CSS 选择器提取 HTML 元素（例如 "article"、"#main"）
trace_redirects	bool	False	在摘要中显示完整的重定向链
assert_status	int | None	None	如果响应状态码与此值不匹配，则报错
assert_contains	str | None	None	如果响应正文中未找到此字符串，则报错（区分大小写）
render_js	bool | None	None	使用无头 Chromium 渲染页面（执行 JS，并等待网络空闲）。需要 playwright。
impersonate	str | None	None	模拟浏览器的 TLS/HTTP2 指纹（例如 "chrome131"），以绕过基于 CDN 指纹的机器人检测。需要 curl-cffi。当 render_js 实际启用时，此项会被忽略。

响应格式

每个响应都以结构化摘要块开头：

--- Request Summary ---
URL:              https://example.com/article
Method:           GET
Injected headers: User-Agent, X-Akamai-Token
Status:           200 OK
Elapsed:          843ms
Response size:    42381 bytes
Output format:    trafilatura
Text extracted:   no
JS rendering:     no
Impersonate:      no
Truncated:        no
Timeout:          60.0s
Proxy:            none
Retry:            disabled
Bot block:        none
Metadata:         extracted
Sanitization:     flag (0 pattern(s) found)
CSS selector:     "article.main-content" (applied)
---

**Title:** Example Article
**Author:** Jane Doe
**Date:** 2024-01-15
**Source:** Example News

---

[Main article content as Markdown …]

---

使用场景

绕过特定域名上的 Akamai 机器人防护

# webfetch.yaml
domains:
  mysite.com:
    headers:
      X-Akamai-Token: "your-token"
      Cookie: "session=abc123"
    output_format: trafilatura

现在，服务会使用你的会话获取 mysite.com 页面，并自动提取干净的文章文本。

---

从新闻网站提取干净的文章内容

domains:
  theguardian.com:
    output_format: trafilatura
    extract_metadata: true

  reuters.com:
    output_format: markdown

---

可靠地调用 JSON API

domains:
  api.example.com:
    output_format: json
    timeout: 10
    retry:
      attempts: 5
      backoff: 1.5
    headers:
      Authorization: "Bearer my-api-key"

响应会以格式化后的 JSON 输出。如果端点返回 application/json，但你忘记设置 output_format，服务会自动检测。

---

通过代理转发企业内网流量

domains:
  internal.corp:
    proxy: "http://proxy.corp:8080"
    headers:
      Authorization: "Bearer my-internal-token"
    timeout: 60

---

自动检测并应对机器人拦截

domains:
  news-site.com:
    bot_block_detection: retry   # retry once with a Chrome User-Agent

在 report 模式下，摘要块会标记拦截，但不会重试。在 retry 模式下，服务会自动使用逼真的 Chrome User-Agent 发起第二次请求。

---

绕过基于 TLS 指纹的 CDN 拦截（JA3 检测）

某些 CDN 会对 TLS 握手本身进行指纹识别（密码套件顺序、扩展、HTTP/2 帧顺序——JA3/JA4），而不只是检查 User-Agent 请求头。伪造请求头在这种情况下不起作用，因为普通的 httpx/Python TLS 仍会呈现出 Python 的特征。impersonate 会通过 curl-cffi 路由请求，逐字节复现真实浏览器的 TLS/HTTP2 特征：

domains:
  fingerprinted-cdn.com:
    impersonate: chrome131   # requires: pip install curl-cffi
    output_format: trafilatura

对于仅因指纹而拦截、且不需要执行 JavaScript 的网站，这是 render_js 的轻量级替代方案。如果某个域名同时需要两者（JS 挑战和指纹匹配），请改用 render_js: true；当同一域名配置了两者时，它会自动优先。

---

防范不可信页面中的提示注入

global:
  sanitize_content: flag    # warn when suspicious patterns are found

domains:
  untrusted-forum.com:
    sanitize_content: strip  # silently remove injection attempts

---

使用 CSS 选择器提取页面的特定部分

在域名的 YAML 配置中进行全局配置：

domains:
  docs.example.com:
    css_selector: "main article"   # only the article content, not nav/sidebar
    output_format: markdown

或在每次调用时传入：

fetch url="https://docs.example.com/guide" css_selector="section#quickstart"

如果选择器未匹配到任何内容，则会回退为使用完整 HTML。

---

对端点进行冒烟测试（CI/CD 风格）

使用 assert_status 和 assert_contains，让工具在响应不符合预期时抛出错误，适用于健康检查和回归测试：

fetch url="https://api.example.com/health" assert_status=200 assert_contains='"status":"ok"'

如果检查失败，客户端会收到清晰的 ValueError，而不是在未提示的情况下返回错误响应。

---

跟踪 URL 的重定向链

fetch url="https://short.ly/abc123" trace_redirects=true

摘要会显示每次跳转：

Redirect chain:
  301  https://short.ly/abc123  →  https://example.com/landing
  200  https://example.com/landing  (final)

---

利用 Cloudflare 内容协商获取适用于大模型的 Markdown

Cloudflare 的 Markdown for Agents 功能会在请求包含 Accept: text/markdown 标头时，在边缘节点将 HTML 转换为 Markdown。与原始 HTML 相比，这可减少约 80% 的令牌用量，而且转换在服务器端完成，比任何本地 HTML 转 Markdown 的流程都更快、更准确。

使用 webfetch_mcp，你可以为每个请求自动注入该标头，也可以仅针对特定域名注入：

# Global — every request negotiates Markdown
global:
  headers:
    Accept: "text/markdown"

# Or per-domain — only for sites you know support it
domains:
  docs.example.com:
    headers:
      Accept: "text/markdown"
    output_format: raw          # Cloudflare already returns Markdown; skip local conversion

Cloudflare 的响应还包含一些实用的额外标头：

标头	描述
x-markdown-tokens	Markdown 文档的估算令牌数，可用于规划上下文窗口
Content-Signal	AI 使用权限（例如 ai-train=yes, search=yes, ai-input=yes）

不支持此功能的网站会忽略该标头并返回普通 HTML，因此全局设置是安全的。你可以使用一条简单的 curl 命令确认是否支持：

curl -sI https://example.com -H "Accept: text/markdown" | grep -i content-type
# text/markdown → supported; text/html → not supported

---

安全性

• 密钥保留在本地 — .env 和 webfetch.yaml 已加入 git 忽略规则；令牌不会离开你的设备。
• 域名隔离 — 仅会为匹配的域名注入标头；无关请求只会收到全局标头。
• 标头注入防护 — 服务器会在发送前检查所有标头名称和值，确保其中不含控制字符。
• 提示词注入清理 — 可选择扫描并标记或移除“ignore all previous instructions”等模式。

---

本地运行（开发）

# Mac / Linux
.venv/bin/python server.py

# Windows
.venv\Scripts\python.exe server.py

服务器通过 stdio（标准 MCP 传输）进行通信，不使用 HTTP 端口。

运行测试套件：

pytest tests/ -v

---

许可证

MIT