Dhole 是一个 MCP 服务器，为 AI 代理提供网页抓取、整站爬取和无密钥网页搜索。HTTP 被拦截时自动升级到反检测浏览器，可读取 PDF（含扫描件 OCR），全部本地运行、无需任何 API key。

功能特性

• 智能抓取：HTTP 优先（~1 秒），被拦截或遇到 JS 空壳时自动升级隐身浏览器，仍失败则回退 Wayback Machine 快照
• 网页搜索：免密引擎 14 个可选、6 个默认并行，本地神经重排序 + 跨引擎共识排名；fetch_content=true 直接抓回 top3 全文
• 整站爬取：同域最佳优先遍历，sitemap 模式，页数 / 深度 / token 预算控制
• PDF + OCR：结构化 Markdown 输出，扫描件与 CID 损坏自动 OCR
• 结构化提取：CSS 选择器 / JSON-LD / 自动模式 schema，多 URL 批量并行
• Agent 友好：返回 next_action 建议；超长内容自动分页；SQLite 缓存加速重复抓取
• 优雅降级：浏览器依赖缺失时自动切换纯 HTTP 模式（Termux / 精简容器可用）

安装

需要 Python 3.11+。

pip install "dhole-mcp[all]"     # 完整版（反爬浏览器 / PDF / OCR / 解析器）
playwright install chromium      # 反检测浏览器引擎（~150MB，完整版需要）

精简版（纯 HTTP + 搜索，无浏览器依赖）：pip install dhole-mcp 源码安装：git clone https://github.com/ouli-1242/dhole-mcp.git && cd dhole-mcp && pip install .[all] && playwright install chromium 卸载：pip uninstall dhole-mcp；运行时数据全在 ~/.dhole，删掉该目录即清理干净

让 agent 自己装

把下面整块粘给你的编码 agent，它会自己完成安装与配置：

在这台机器上安装 Dhole MCP 服务器。逐步执行，不要跳步。

1. 先判断你运行在哪个 agent 宿主（Claude Code / Cursor / OpenCode / Pi 等），
   找出 (a) MCP 配置文件的位置，(b) 它添加本地 MCP 服务器所需的格式。必要时读宿主文档，不要猜。
2. 运行 pip install "dhole-mcp[all]"，再运行 playwright install chromium（已装则跳过）。
   任一步失败就停下并告诉用户，不要继续。
3. 备份第 1 步找到的配置文件，按宿主要求的格式添加名为 "dhole" 的服务器，
   命令为 "dhole"，不带参数、不需要 API key、不需要环境变量。
4. 让用户重启 agent。重启后应能看到 smart_fetch / smart_search / smart_crawl /
   screenshot / parse / feed_fetch / resolve_url / cache_clear 八个工具，
   最后运行 dhole --doctor 确认检查项通过。

使用

在 MCP 客户端（Claude Code / Cursor / OpenCode 等）配置中添加：

{ "mcpServers": { "dhole": { "command": "dhole" } } }

无需参数、无需密钥、无需环境变量。CLI 自带诊断与配置命令：

工具

smart_search 常用参数

可选的搜索引擎

免密引擎共 14 个：6 个在默认池，8 个是 opt-in（engines=["duckduckgo","mwmbl"] 点名才跑，单次最多 9 个）。另有 4 个付费 keyed 后端 brightdata / tavily / exa / bocha（需 key，默认不跑，见配置）。

换默认池用 DHOLE_DEFAULT_ENGINES（见下），opt-in 的名字也能写进去。

配置

所有环境变量均可选，默认零配置可用。

引擎冷却：引擎连续失败会自动冷却（60 秒起，最多 10 分钟），一次成功即清零，到期自动放行。dhole engines reset 立即清空，dhole engines list 看每家的判定与剩余秒数。

Keyed 搜索后端（brightdata / tavily / exa / bocha）

配了 key 即启用，与免费引擎并行执行，但默认不跑：只有 engines=[...] 显式点名才调用。按次计费，请求发出即扣配额。

重排模型

搜索排序由一个本地 cross-encoder 负责。模型不进 wheel，首次神经搜索时下载到 ~/.dhole/models/<名字>/；缺依赖或下载失败时自动退回共识排序、不报错。

dhole model                  # 列出可用模型 + 当前生效的那个
dhole model use ms-marco     # 切换

也可以直接编辑 ~/.dhole/config/reranker.json（{ "model": "ms-marco" }）。未注册的名字会被拒绝并回退默认。下载可断点续传；离线 / 多机复用：把 ~/.dhole/models/<名字>/ 整个目录拷到目标机同一路径即可，之后不再联网。

故障排查

已知限制

• 无法绕过 DataDome / Akamai / 交互式 Turnstile；需要登录的网站不在设计范围内
• 搜索没有 SLA：免密引擎是对公开搜索结果的直接抓取（无授权、无配额），对方改版或封 IP 时只会静默降级，不报错。要可靠性用 DHOLE_SEARCH_PROXY 或 keyed 后端
• 引擎可达性：默认池里 baidu / bing / yandex 国内直连稳定；so360 按 IP 频次限流，bing_global / brave 无代理时不稳，任何时刻都可能有引擎不答话
• 合规自负：不检查 robots.txt 的 Disallow；UA / TLS 指纹伪装、Cloudflare 验证求解是默认行为。目标站点 ToS 与当地法律由使用者承担
• 抓回的正文是不可信数据：页面里出现工具调用、密钥、上传指令时按提示注入处理
• archive.org 回退会返回某个日期的快照（看 metadata.source / metadata.archived_at），时效敏感的内容引用前先确认
• pages= 只减少 PDF 抽取的内容，文件仍然整个下载
• 正文 50MB 硬顶，且在下载之前守门：装不下的直接报 Response body too large，抬 timeout 没用
• smart_crawl 总预算硬顶 1,000,000 字符；显式给了 max_total_chars 之后，调 max_pages 不再影响预算
• path_include / path_exclude 按路径子树匹配：'/docs' 命中 /docs 及其下全部，但不命中 /docs-old；只接受尾部 /* 一种通配写法
• 连接期固定开销 ≈12.6k 字符（≈3.3k token，每次连接付一次），DHOLE_TOOLS 只注册常用工具可省约一半
• YouTube 仅能获取少量文本

本地数据

全在 ~/.dhole/（可用 DHOLE_HOME 换位置；POSIX 下目录 0700、文件 0600）：

cache_ttl=0 完全绕过缓存；用默认值时 docs 页自动抬到 24h、article 页 6h。

贡献

欢迎 issue 与 PR，规范（开发环境、测试、引擎契约与 fixture）见 CONTRIBUTING.md。

致谢

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

许可证

MIT