Dhole

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

功能特性

• 智能抓取：HTTP 优先（~1 秒），被拦截或遇到 JS 空壳时自动升级 Patchright 隐身浏览器并求解 Cloudflare 验证；全部失败时回退 Wayback Machine 快照
• 网页搜索：多引擎并行（bing / duckduckgo / brave / yahoo / yandex 等），本地 ONNX 神经重排序，跨引擎共识排名；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
rm -rf ~/.dhole                 # 运行时缓存（Windows: rd /s /q %USERPROFILE%\.dhole）

使用

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

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

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

dhole -v    # 查看版本 + 更新状态
dhole -u    # 自更新（本 fork 默认关闭）

工具

smart_search 常用参数

配置

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

免密引擎连续 3 次连接失败（DNS/拒连/超时，通常是被墙）会自动冷却 10 分钟并持久化，期间不再参与搜索；任何一次成功即清零。被反爬封（403/503）的冷却仍是 60 秒。 |

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

设了 DHOLE_BRIGHTDATA_API_KEY 即启用，没有额外开关。它向 api.brightdata.com/request 请求 google.com/search 的结果页（data_format=parsed_light），与免费引擎并行执行。

• 按次消耗，且默认不跑：keyed 引擎只有 engines= 显式点名才执行（命中搜索缓存则连调用都不发）
• engines=["brightdata"] 可单独选它：只跑付费后端；未配 key 时报错直指 DHOLE_BRIGHTDATA_API_KEY，不会把你引去查代理。可选引擎名全部来自 _DHOLE_TO_BACKEND 这一张表 —— 8 个免密的加它
• 不拉高共识门槛：min_engines = min(3, 免费引擎数) 只按免费引擎计算，它不计入
• 提前返回时不取消：免费引擎凑够结果触发早退时，其余任务被 cancel，但 Bright Data 会等它跑完，避免已花出去的配额白花
• 失败大多静默：非 200 或任何异常都返回空列表、只记 debug 日志，不影响本次搜索结果。401/403 除外 —— key 错误或过期会抛 BrightDataAuthError，在 status 里显示为 error:BrightDataAuthError，不会伪装成「没有结果」；它也不触发熔断（key 错了冷却 60 秒毫无意义）
• 单次 HTTP 超时取 max(DHOLE_SEARCH_DEADLINE, 20)：默认（deadline 16 秒）下仍是 20 秒 —— SERP 渲染要时间，且配额在请求发出那一刻就已花掉；但你调高 deadline 它会跟着涨
• 失败响应体写日志前会先脱敏。注意 security.redact_api_key() 的正则只认 sk-/pk-/api_key- 前缀和带凭据的代理 URL，盖不住 Bright Data 自己的 key 形状，所以额外拿已知 key 做了定向替换

已知限制

• 无法绕过 DataDome / Akamai / 交互式 Turnstile；需要登录的网站不在设计范围内
• duckduckgo / brave / yahoo 需要 VPN 可达（bing / yandex 国内直连）
• 搜索引擎限速时熔断器自动冷却 60 秒，重度使用建议配置代理
• YouTube 仅能获取少量文本

贡献

欢迎 issue 与 PR，规范见 CONTRIBUTING.md。

致谢

本项目是 dondai1234/master-fetch 的二创（衍生作品），上游以 MIT 协议发布，原始版权文本已完整保留于 LICENSE。src/dhole_mcp/search_metasearch.py 派生自 ddgs，声明见 NOTICE.ddgs.txt。

许可证

MIT