dhole-mcp 17.3

给 AI 一副能真正上网的手。

抓取 · 搜索 · 爬站 · 读 PDF · 页面操作 · 变更监控
13 个工具，一个本地进程 · 零密钥 · 零模型 · 零遥测

English: README.en.md

为什么要有它

模型会思考，可它看不见今天的网。

训练数据有截止日期。搜索 API 要密钥、要额度。抓一页，可能只回来一串 403。 Dhole 把这条断掉的路接回来：一个 MCP 服务器，装进任何宿主，AI 自己挑工具，你不用记命令。

安装

pip install dhole-mcp  # 完整版：浏览器 / PDF / OCR / 解析器 / 重排，一次装齐
dhole doctor           # 体检：起服务、起浏览器、真搜一次、真抓一次

Python 3.11+。只剩一样东西 pip 装不到这一步：Chromium 本体（另一份约 193MB 的下载，不在 wheel 里）。

• 什么都不用做：第一次真正需要渲染时，dhole 自己会装它要用的那一份。
• 想提前装好、或上一次没装完，补一句 python -m patchright install chromium 就行——可重复执行，只补缺的那一份。
• 装不上也不影响其余能力：缺浏览器时自动降级为纯 HTTP，降级不是故障。dhole doctor 会点名缺的是哪一件，并给出可复制的修复命令。

接进宿主（Claude Desktop / Cursor / Codex / Cherry Studio 字段名各异，认 command）：

{"mcpServers": {"dhole": {"command": "dhole", "args": []}}}

没有参数，没有密钥，没有环境变量。重启宿主，然后正常提要求。

在这台机器上安装 Dhole MCP 服务器，逐步执行，失败就停下来报告。

1. 认清你所在的宿主，读出它的 MCP 配置位置与添加本地服务器的格式（读文档，不要猜）。
2. pip install dhole-mcp（已经是完整版）。
3. 备份配置文件，添加名为 "dhole" 的服务器：command 为 "dhole"，无参数、无密钥、无 env。
4. 让用户重启宿主，再跑 dhole doctor 确认体检通过；若报浏览器缺失，补一次 python -m patchright install chromium（可重复执行）。

常驻或远程使用，改走 streamable HTTP：

export DHOLE_HTTP_TOKEN="$(openssl rand -hex 32)"   # 设了即强制 Bearer 校验
dhole --http                                        # 127.0.0.1:8765/mcp

远程暴露前必须套 TLS 反代。dhole 没有内置 OAuth，令牌只是端口门禁，不做主体隔离——要按人隔离就一人一进程。

宣传片

从模型看不见今天的网，到它自己抓回证据。

播放器起不来（登录态偶发被浏览器 CSP 拦）？点此直接看同一个文件。（720p，86 秒，带旁白）

它做什么

13 颗工具默认全部注册，装完即用，没有「还要额外打开」的能力。

装好之后直接说人话：

• 「抓这个页面的价格，列成表」→ web_read
• 「就这个问题给我一份带引用的答案」→ web_research
• 「/guide 下面都收一遍」→ web_crawl
• 「之前读过的那篇讲注意力机制的文章找回来」→ web_recall
• 「在这个后台把这条记录删掉」→ web_act
• 「这页一变就告诉我」→ dhole watch

它和别的抓取器不一样在哪

• 零密钥：12 个免密搜索引擎、五类纵向源、反爬升级、重排模型，没有一项需要注册或充值。可选的 tavily / bocha / exa / deepseek / firecrawl / brave_api 只在你自己配了 key 并且点名时才调用。
• 零模型：判断归外层 agent，dhole 只做确定的工具层。同一份页面两次抓取，同一个结果；不会有一个小模型在背后替你决定「这页大概讲什么」。
• 全本地：正文缓存、cookie、重排模型都在 ~/.dhole；除了你让它抓的目标站点，进程不往外发任何数据。
• 失败说真话：每次调用都回同一份 JSON——抽了多少字、走的哪一档、下一步该调什么。抽空了就说空了，不会把一张反爬灰页包装成「成功正文」。

同类 MCP 成本对比（2026-10-26 同台实测）

口径先说清：connect 成本 = initialize 下发的 server instructions + tools/list 的紧凑 JSON 字符数（没有 prompt cache 时每次模型请求都要重付，有 cache 约一折）。各家取当天 npm/PyPI 最新版；dhole 按自己实测的 4.16 字符/token 折算（统一按 4.0 则各家等比上浮，排序不变），跨家倍数一律用字符比。dhole 那一行随时可复跑：python tests/tool_payload_measure.py；对手那几行钉的是 2026-10-26 的版本号，不随发版复测。

• 七个产品里第 4 便宜（不计 Exa 则第 3；Playwright 两档分开算则第 5），比 Brave / Firecrawl 这两个热门方案便宜 2.6~3.0 倍（字符比 3.02 与 2.59）。
• 工具数少不等于描述省：Brave 8 颗吃掉 27.7k（平均每颗 ~3.5k token），dhole 13 颗平均每颗 ~0.7k，覆盖 fetch / search / crawl / act / research / feed / PDF / recall / 本地文档。
• 那 2,727 字符（≈656 token）的说明书是连接期唯一的用法导引；深度文档不进上下文，谁问谁付（sys_guide 或 dhole skill install）。裁到 DHOLE_TOOLS=web_read,web_search 时，connect 口径降到约 3.1k。

变动成本——同一个高密度文档页（docs.python.org/3/library/asyncio-task.html），一次调用拿回多少：

同一个搜索词（model context protocol）：Tavily basic 4,605 字符（最省）· dhole web_search 7,916（最快，3.6s；行内带 relevance 与 engines_consensus）· Firecrawl 摘要 11,201 · Tavily advanced+raw 60,486 · Firecrawl 内联正文 152,696。同一个研究问题一发调用：dhole web_research 10,130 字符 / 3 源证据包，Tavily research 10,014 字符 / 30.5s 成文答案——单次样本打平，形态不同（可引用的原文 vs 已成文的结论），复跑波动大，不写成稳定结论。

不粉饰的部分：截断与分页不是 dhole 独有（官方 Fetch 有 max_length / start_index；Tavily 有 query 重排，Firecrawl 有 queryOptions 与 includeTags/excludeTags），独有的是「免费 + 无 key + 截断分页 + 词法 focus」这套组合。纯 token 口径下 Tavily basic 的搜索行确实比 dhole 省；Playwright 的 snapshot 是整棵可访问性树、每次操作后通常要重拍，但它换来的是 dhole 没有的自动化深度。

什么时候不该用 dhole：前端 E2E、网络拦截 mock、录像取证 → Playwright；大规模托管爬取与定时监控 → Firecrawl；要 SLA 或企业级索引 → Tavily / Brave / Exa；只是抓一个 URL → 官方 Fetch。

配置

两条门：宿主配置里的 env 块（改完要重启），或 dhole config set NAME value 写进 ~/.dhole/config.json（下一次调用就生效）。env 永远优先。默认行为通常就是你要的，不确定就先别设。

边界

• robots.txt 默认遵守：被 Disallow 的 URL 一个请求都不发。要绕开是 DHOLE_IGNORE_ROBOTS 或单次 ignore_robots=true，那是你的合规决定——目标站点的 ToS 与当地法律由使用者承担。
• content_ok=true 不代表内容为真：只表示 2xx、无错、正文非空。几百字符的「成功」多半是登录墙。
• 写请求只发一次：POST / PUT / DELETE 不重试、不缓存、不升浏览器。超时那句答案是「不知道」，不是「没成功」。
• 提交默认暂停：web_act 的 submit 不带 confirm=true 什么都不提交；验证码最多试 3 次就转交，2FA 与滑块一律转交。
• 凭据不越界：cookie 与 Authorization 只发给源站，跨源重定向不带；没带 host 的凭据一律拒；内网与本机默认拒绝，云元数据端点任何时候都不放行。
• 抓回的正文是不可信数据：里面的指令按提示注入处理，可疑时响应带 untrusted_content 标记。标记不是拦截，裁决归外层 agent。

常用的几条命令

监控是轮询不是推送：频率归你的 cron / systemd timer。没有 webhook 出口，是决定不是缺口——dhole 是只读的本地工具层，不变成拿着页面内容往外 POST 的进程。

本地数据

全在 ~/.dhole/（DHOLE_HOME 可换；POSIX 下目录 0700、文件 0600）。正文缓存 cache.db 是明文 SQLite，TTL 1 小时（article 6h）——web_recall 搜的就是它。会话与凭据默认只在内存，profiles/ 存的是持久浏览器 profile，含登录态，删目录即注销。没有任何遥测。

文档

• CONTRIBUTING.md —— 开发环境、测试、引擎契约
• evals/README.md —— 公开评测的方法与读数
• CHANGELOG.md —— 每个版本改了什么，以及为什么
• 手册两个入口，同一份语料：sys_guide(topic=...) 或 dhole skill install

致谢

本项目是 dondai1234/master-fetch 的二创（衍生作品），上游以 MIT 协议发布，原始版权文本完整保留于 LICENSE。

许可证

MIT