Stealth Fetch MCP

隐形蚀刻_mcp

stealth_fetch_mcp 是一个Python MCP服务器，用于获取和解析web内容 使用浏览器级TLS指纹模拟 curl_cffi.

它专为需要以下功能的MCP客户端（Claude Code/桌面、Codex等）而设计 当默认Python HTTP签名被阻止时，更具弹性的获取工具。

为什么选择此服务器

• 用途 curl_cffi 模拟配置文件（默认值： chrome)用于类似浏览器的TLS/HTTP行为。
• 为HTML、可读文本、JSON API和链接提取提供专注的获取工具。
• 添加了实用的保护措施：截断、可操作的错误消息和严格的输入验证。

特性

• stealth_fetch_page：使用浏览器模拟获取原始HTML。
• stealth_fetch_text：获取并返回干净的可读性样式文本。
• stealth_fetch_json：获取JSON API（GET/POST）并漂亮地打印JSON。
• stealth_extract_links：使用CSS选择器和正则表达式过滤提取链接。
• stealth_fetch_headers：返回HTTP状态、最终URL和JSON格式的响应头。
• stealth_extract_metadata：将JSON-LD、Open Graph、Twitter Card和元标签提取为JSON。
• stealth_extract_tables：将所有HTML表提取为JSON格式，并自动检测标头。
• stealth_fetch_feed：获取RSS 2.0或Atom提要并将其解析为结构化JSON。
• stealth_fetch_bulk：同时获取多个URL，并对每个URL进行错误隔离。

所有工具包括：

• 只读且幂等
• 注释为开放世界MCP工具
• 受输出截断保护([truncated at {n} chars])
• 通过集中、可操作的错误处理实现

需求

• Python 3.12+
• uv / uvx

项目布局

stealth-fetch-mcp/
├── pyproject.toml
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── src/
│   └── stealth_fetch_mcp/
│       ├── __init__.py
│       ├── client.py
│       ├── parser.py
│       └── server.py
└── tests/

本地设置

cd /Users/miller/projects/curl_mcp/stealth-fetch-mcp
uv sync

运行MCP服务器

uv run stealth-fetch-mcp

您也可以直接运行：

uv run python -m stealth_fetch_mcp

工具参考

stealth_fetch_page

• url （必填）
• impersonate （默认值： "chrome")
• headers （可选对象）
• timeout （默认值： 30)
• follow_redirects （默认值： true)
• session_options （可选对象； curl_cffi.AsyncSession 配置）
• request_options （可选对象；根据请求 curl_cffi 配置）
• max_chars （默认值： 100000)
• 返回：原始HTML字符串

stealth_fetch_text

• url （必填）
• impersonate （默认值： "chrome")
• selector （可选CSS选择器）
• session_options （可选对象； curl_cffi.AsyncSession 配置）
• request_options （可选对象；根据请求 curl_cffi 配置）
• max_chars （默认值： 50000)
• 返回：已清理的markdown文本内容

stealth_fetch_json

• url （必填）
• impersonate （默认值： "chrome")
• headers （可选对象）
• method ("GET" 或 "POST"，默认值： "GET")
• body （POST的可选JSON字符串）
• session_options （可选对象； curl_cffi.AsyncSession 配置）
• request_options （可选对象；根据请求 curl_cffi 配置）
• max_chars （默认值： 100000)
• return：打印精美的JSON字符串

stealth_extract_links

• url （必填）
• impersonate （默认值： "chrome")
• selector （默认值： "a[href]")
• pattern （可选正则表达式打开 href)
• max_results （默认值： 100)
• session_options （可选对象； curl_cffi.AsyncSession 配置）
• request_options （可选对象；根据请求 curl_cffi 配置）
• max_chars （默认值： 100000)
• 返回：JSON列表 {text, href, absolute_url}

stealth_fetch_headers

• url （必填）
• impersonate （默认值： "chrome")
• headers （可选对象）
• timeout （默认值： 30)
• follow_redirects （默认值： true)
• session_options （可选对象）
• request_options （可选对象）
• 返回：JSON对象 {"status_code": int, "final_url": str, "headers": object}

stealth_extract_metadata

• url （必填）
• impersonate （默认值： "chrome")
• session_options （可选对象）
• request_options （可选对象）
• max_chars （默认值： 100000)
• 返回：JSON对象 {"json_ld": [...], "opengraph": {...}, "twitter": {...}, "meta": {...}}

stealth_extract_tables

• url （必填）
• impersonate （默认值： "chrome")
• selector （可选CSS选择器，用于限定表搜索范围）
• session_options （可选对象）
• request_options （可选对象）
• max_chars （默认值： 100000)
• 返回：JSON列表 {"headers": [...], "rows": [[...], ...]}

stealth_fetch_feed

• url （需要RSS 2.0或Atom提要URL）
• impersonate （默认值： "chrome")
• max_items （默认值： 50，最大值： 500)
• session_options （可选对象）
• request_options （可选对象）
• max_chars （默认值： 100000)
• 返回：JSON对象 {"feed_title": str, "feed_link": str, "items": [{"title", "link", "published", "summary"}]}

stealth_fetch_bulk

• urls （必填列表 {"url": str} 对象，1-50个条目）
• impersonate （默认值： "chrome")
• max_concurrency （默认值： 5，最大值： 20)
• delay （默认值： 0.0 秒；在获取信号量时隙后，在每次请求之前休眠）
• timeout （默认值： 30)
• session_options （可选对象）
• max_chars_per_url （默认值： 10000)
• 返回：JSON列表 {"url", "status": "ok"|"error", "status_code"?, "final_url"?, "text"?, "error"?}

curl_cffi 期权覆盖范围

此MCP现在公开了实用 curl_cffi 配置界面通过：

• session_options：用于创建临时会话的会话级别默认值 AsyncSession 对于那个工具调用。
• request_options：传入的每个请求覆盖 AsyncSession.request(...).

session_options 领域

• headers, cookies, auth
• proxies, proxy, proxy_auth
• base_url, params
• verify (bool 或CA包路径 str)
• timeout (float 或 (connect, read) 元组）
• trust_env, allow_redirects, max_redirects
• impersonate, ja3, akamai, extra_fp
• default_headers, default_encoding
• http_version (v1|v2|v2tls|v2_prior_knowledge|v3|v3only)
• debug, interface, cert
• discard_cookies, raise_for_status
• max_clients
• curl_options （低级CurlOpt覆盖）

request_options 领域

• params, data, json
• headers, cookies, auth
• timeout, allow_redirects, max_redirects
• proxies, proxy, proxy_auth
• verify, referer, accept_encoding
• impersonate, ja3, akamai, extra_fp
• default_headers, default_encoding
• quote, http_version, interface, cert
• max_recv_speed, discard_cookies
• curl_options （低级CurlOpt覆盖）

curl_options 格式

curl_options 接受以下列表 {option, value} 条目：

• option 可以是：

- CurlOpt名称： "TIMEOUT_MS" - 完全限定名称： "CurlOpt.TIMEOUT_MS" - 数字选项id（整数或数字字符串）

• value 支持原始JSON值(string, number, boolean)

故意约束

• request_options.stream=true 被拒绝，因为工具输出返回缓冲文本/JSON，而不是流式帧。
• 出于安全性和确定性考虑，MCP模式中有意不公开以多部分上传/回调为中心的请求模式。

研究简报

配置覆盖范围是从以下内容构建的 curl_cffi 主要来源：

• API签名和会话/请求选项文档： API 参考
• 使用模式和模拟行为： 快速开始
• 支持的模拟目标： 模拟目标
• 确切的运行时kwargs处理：

- curl_cffi/requests/session.py (AsyncSession.__init__, AsyncSession.request) - curl_cffi/requests/utils.py (set_curl_options)

架构说明

• client.py：共享 AsyncSession 工厂、获取包装器和集中错误映射。
• parser.py：HTML清理/可读性提取、URL解析、链接提取。
• server.py：FastMCP服务器、生命周期管理共享会话、工具注册、Pydantic模型。

MCP配置（uvx）

使用 uvx --from 在不发布一揽子计划的情况下，促进当地发展。

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "stealth-fetch": {
      "command": "uvx",
      "args": ["--from", "/path/to/stealth-fetch-mcp", "stealth-fetch-mcp"]
    }
  }
}

克劳德代码

claude mcp add stealth-fetch -- uvx --from /path/to/stealth-fetch-mcp stealth-fetch-mcp

Codex命令行界面/应用程序

codex mcp add stealth-fetch -- uvx --from /path/to/stealth-fetch-mcp stealth-fetch-mcp

开发和测试（TDD）

uv run pytest -q
uv run pytest --cov=stealth_fetch_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src

验证命令

uv run python -c "from stealth_fetch_mcp.server import mcp; print('OK')"
uv run python -m stealth_fetch_mcp
uv build
claude mcp add --help
codex mcp add --help

限制和安全

• 此服务器提高了传输级别的兼容性，但它不是验证码求解器。
• Robots.txt的合规性是自动的——服务器通过其MCP进行通信

instructions 参数，因此消费模型不需要手动检查。

• 始终遵守网站服务条款，并适用合理的费率限制。
• 保持请求范围的针对性；避免抓取敏感或受限的内容。

许可证

MIT。看 LICENSE.

贡献

看 CONTRIBUTING.md.