Web Research MCP

一个高质量、多来源的 Web 研究 MCP 服务器，专为 AI 智能体设计。将其接入 Claude Desktop、Hermes、Cursor 或任何兼容 MCP 的客户端，即可获得生产级的搜索 + 页面抓取能力，覆盖 Wikipedia、arXiv、Hacker News、Stack Exchange、Crossref、Brave、Tavily 以及互联网上的任意 URL。

# One-line install (anywhere on disk)
git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research --command "$(pwd)/web-research-mcp/bin/web-research-mcp"
# 6 of 7 tools work with zero API keys. Add Brave or Tavily to unlock general web search.

为什么存在这个项目

大多数"Web 搜索"MCP 服务器试图通过带随机指纹的无头浏览器抓取 Google。这种方法是一场必输的军备竞赛——搜索引擎会在几天内检测并封禁爬虫，即使侥幸成功，你得到的也是需要 LLM 自行清理的 DOM 垃圾。

本服务器采用了不同的方法——它对接的是为智能体而生的 API：

全部七个数据源无需任何 API 密钥即可使用。添加 Brave 或 Tavily 密钥可解锁实时通用 Web 搜索。这是最高质量的方法——你获得的结果优于爬虫，因为真正的 Web 索引 API 使用的信号（点击模型、新鲜度、链接分析）是任何爬虫都无法复制的。

快速开始

方案 A — pip install（发布后可用）

pip install deep-web-research-mcp
hermes mcp add web-research --command "$(which web-research-mcp)"

关于命名的说明。 PyPI 发行包名称为 deep-web-research-mcp（因此使用 pip install deep-web-research-mcp），但安装后位于 PATH 上的可执行文件名为 web-research-mcp（由 pyproject.toml 中的 [project.scripts] 定义）。这是有意为之——可执行文件名与本地启动器 bin/web-research-mcp 以及 MCP 注册名 web-research 保持一致。同一个包，两个名称。

方案 B — 从源码克隆

git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research \
  --command "$(pwd)/bin/web-research-mcp"

当提示时，接受全部 7 个工具。完成。

方案 C — 通过 Claude Desktop 安装

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/code/mcp-servers/web-research/bin/web-research-mcp"
    }
  }
}

方案 D — 通过 Cursor / 任意 stdio MCP 客户端安装

{
  "mcpServers": {
    "web-research": {
      "command": "/absolute/path/to/web-research-mcp/bin/web-research-mcp"
    }
  }
}

启动器脚本会在首次运行时自动创建虚拟环境，从 pyproject.toml 安装依赖，并加载 web-research.env 以读取你配置的任何 API 密钥。

2.（可选）添加 API 密钥以启用真正的 Web 搜索

cp web-research.env.example web-research.env
$EDITOR web-research.env

启动器在每次调用时都会从 web-research.env 读取密钥——无需重启 MCP 客户端。

3. 使用它

向你的智能体提问，例如：

"在 Hacker News 和 Stack Overflow 上搜索 2026 年发布的最佳 MCP 服务器"

"使用 pro_mode 研究小型语言模型的当前状态"

"抓取 https://arxiv.org/abs/2506.06962 并总结其方法论"

"将这一论断与 Wikipedia 和 arXiv 进行交叉验证"

工具

tools/list 中注册了全部 10 个工具。工具分为两层：

• 搜索与抓取（7 个工具）——单次查询。一个工具、一个 API、一个结果。

• 深度研究（3 个工具）——多步骤流水线，负责规划、收集和整理证据。当单次搜索不够用时使用这些工具。

搜索与抓取

search_web — 多来源通用 Web 搜索

search_web(
    query: str,                  # search query
    max_results: int = 10,       # per source, before dedup (1–30)
    pro_mode: bool = False,      # also fetch top 3 URLs and append excerpts
) -> str

由 Brave + Tavily 提供支持，具备 URL 规范化去重和跨来源分数提升。需要 BRAVE_API_KEY 和/或 TAVILY_API_KEY。没有密钥时，会返回一条清晰的消息，告诉你如何启用它。

pro_mode: true 是研究利器功能——它会执行一次普通搜索，通过 Jina 抓取前 3 条结果，并将内容附加为摘要。一次调用即可完成原本需要 search_web + 3 次 fetch_url 的工作。

fetch_url — 任意页面的干净 Markdown

fetch_url(url: str) -> str

通过 Jina Reader 处理，它能够：

• 渲染 JS 密集型页面（SPA、React 应用）

• 绕过大多数机器人检测（Jina 在白名单中）

• 返回带元数据块（Title:、URL Source:、Published Time:）的干净 Markdown

• 截断至约 20k 字符以保护你的上下文窗口

search_wikipedia — 百科知识锚定

search_wikipedia(query: str, max_results: int = 5) -> str

Wikipedia MediaWiki API。无需密钥。速度快。最适合定义和历史背景。

search_academic — arXiv 预印本

search_academic(query: str, max_results: int = 5) -> str

返回标题、作者、摘要片段、发表日期、PDF 链接。无需密钥。最适合计算机科学、物理学、数学、生物学。

search_news — Hacker News 信号

search_news(query: str, max_results: int = 10) -> str

返回标题、URL、分数、评论数、日期。无需密钥。最适合了解当下科技趋势。

search_stackexchange — 来自 180+ 站点的问答

search_stackexchange(query: str, max_results: int = 5, site: str = "stackoverflow") -> str

将 site 设置为任意 SE 社区：serverfault、superuser、askubuntu、math、tex、datascience、ai 等。无需密钥。

search_scholar_meta — 通过 Crossref 检索同行评审论文

search_scholar_meta(query: str, max_results: int = 5) -> str

返回标题、DOI、引用次数、出版商、发表日期、摘要。覆盖 arXiv 未收录的论文（Elsevier、Springer、Wiley、IEEE、ACM）。无需密钥。

深度研究

这三个工具将上述搜索/抓取原语组合成多步骤研究流水线。它们本身从不调用 LLM——由调用方模型负责撰写最终叙述；服务器的职责是规划、收集和整理带有可验证引用的证据。

plan_research — 仅生成结构化计划（不执行抓取）

plan_research(question: str, depth: str = "standard") -> str  # JSON

返回一个 JSON 研究计划：子问题、每个子问题推荐的来源、理由、要执行的查询，以及预估的搜索和抓取次数。当你希望在提交完整流水线之前检查或修改计划时使用此工具。

• depth："quick"（2-3 个子问题）、"standard"（4-6 个）、"deep"（6-8 个）

extract_evidence — 从单个 URL 提取针对性引文

extract_evidence(
    url: str,
    question: str,
    max_passages: int = 5,
) -> str  # JSON

通过 Jina 抓取 URL，将其拆分为段落，根据与你的问题的相关性对每段打分，并返回最相关的段落。每个段落都包含 before / quote / after 上下文、relevance 分数（0-1）以及 offset（在源文档中的字符位置），因此引用可以独立验证。

当你已经有一个特定来源，并希望深入挖掘其中针对某个狭窄论断的证据时使用此工具。

research — 完整深度研究流水线

research(question: str, depth: str = "standard") -> str  # markdown + JSON

端到端研究工作流：

1. 规划——构建子问题计划

2. 扇出——并行地在每个子问题的推荐来源中执行搜索

3. 排序——在整个计划中去重 URL，使用来源感知的复合评分进行排序（Wikipedia/arXiv/Crossref 2.0×、Stack Exchange 1.7×、Web 搜索 1.5×、Hacker News 1.0×）

4. 抓取——通过 Jina Reader 拉取排名靠前的 URL

5. 提取——对段落进行相关性评分并设置质量下限（过滤掉导航菜单、纯链接段落、页脚垃圾内容）

6. 返回——输出结构化的 ResearchReport：

{
  "question": "What is retrieval augmented generation?",
  "depth": "quick",
  "plan": { "sub_questions": [...], "estimated_searches": 4, ... },
  "citations": [
    { "id": 1, "url": "...", "title": "...", "source": "wikipedia", "quotes": 2 }
  ],
  "evidence": {
    "sq_def": [
      { "citation_id": 1, "relevance": 0.78, "offset": 1234,
        "before": "...", "quote": "...", "after": "..." }
    ]
  },
  "synthesis_template": "# Research Report: ..."
}

synthesis_template 是一个 Markdown 骨架，每个子问题对应一个章节，外加一个 Sources 表格。你（模型）负责填充叙述，将每个 [n] 标记与 citations 中对应的条目关联起来。每条引用的段落都带有字符 offset，读者可以据此对照原始页面验证引用。

depth 控制广度：

• "quick" — 2-3 个子问题，约 6 次抓取，约 2 分钟

• "standard" — 4-6 个子问题，约 20 次抓取，约 3 分钟

• "deep" — 6-8 个子问题，约 32 次抓取，约 5 分钟

架构

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│  (Claude Desktop, Hermes, Cursor, custom agent)          │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC over stdio
                     ▼
┌─────────────────────────────────────────────────────────┐
│              bin/web-research-mcp                         │
│  • Boots venv (or reuses cached one)                     │
│  • Sources web-research.env for API keys                 │
│  • Execs python -m web_research.server                   │
└────────────────────┬────────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────────┐
│           web_research.server (MCPServer)                 │
│  7 tool functions registered via @app.tool() decorator    │
│  • Pydantic-driven JSON schemas from type hints           │
│  • Single shared httpx.AsyncClient per call              │
│  • Graceful degradation: one bad source ≠ failed call    │
└────────────────────┬────────────────────────────────────┘
                     │ asyncio.gather for parallel fan-out
                     ▼
┌─────────────────────────────────────────────────────────┐
│          web_research.providers (7 backends)              │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ brave    │ │ tavily   │ │ jina_fetch  │  ← general web│
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ wikipedia│ │ arxiv    │ │ crossref    │  ← academic   │
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐                                │
│  │ hn_algolia│ │stackex   │  ← tech signal               │
│  └──────────┘ └──────────┘                                │
│  + merge_results() with URL-canonical dedup               │
└─────────────────────────────────────────────────────────┘

关键设计决策

API 优先，而非爬虫优先。 这是核心论点。每个数据源都是为程序化访问而设计的官方 API。你获得干净的结构化数据，没有 IP 封禁，网站改版时也无需维护负担。

按来源隔离错误。 每个提供方都将其 HTTP 调用包裹在 try/except 中。某个来源返回 429 绝不会拖垮整个搜索——你会获得部分结果，同时收到一条清晰的消息说明哪个来源失败了。

URL 规范化。 merge_results() 在去重前剥离跟踪参数（utm_*、fbclid、gclid、ref），对主机名进行大小写归一化，并丢弃片段。当 Brave 和 Tavily 返回同一篇文章时，你只会看到一次，并带有 also_found_in: [brave, tavily] 和提升后的分数。

每次调用共享 HTTP 客户端。 httpx.AsyncClient 支持连接池（max_connections=20）、合理的超时（默认 30s，fetch_url 为 45s）以及自动重定向跟随。每次调用新建客户端，因为 stdio MCP 服务器一次只处理一个请求，我们希望保持干净的状态。

不使用无头浏览器。 零 Playwright、Selenium、Puppeteer 或代理轮换。攻击面更小、依赖更少、无 JVM/Chrome 占用。少数需要 JS 渲染的站点由 Jina 承担繁重工作。

与替代方案对比

测试

.venv/bin/python tests/e2e_protocol.py

这会启动真实的服务器，执行一次真实的 MCP initialize + tools/list 握手，然后对每个工具发起实时的 JSON-RPC 调用，并验证：

• 真实 API 返回真实数据（而非桩数据）

• 每个工具的响应具有预期的结构

• 错误状态得到优雅处理

• 没有密钥时 search_web 返回清晰的"设置 API 密钥"消息

上次运行：7/7 个工具全部通过实时 API 测试。

故障排查

服务器已启动但工具未显示在 MCP 客户端中

检查 hermes mcp list（或等效命令）。服务器以 --command 方式注册，这意味着 Hermes 会直接执行启动器。确保启动器具有可执行权限：

chmod +x bin/web-research-mcp

fetch_url 返回截断的内容

这是有意为之——20k 字符上限保护你的上下文窗口。若需阅读更长内容，请自行获取页面，将摘录片段传给 search_web 进行后续提问，或通过多次调用分段处理。

search_web 返回 "No web results. This is likely because no API key is configured"

你需要在 web-research.env 中至少设置 BRAVE_API_KEY 或 TAVILY_API_KEY 中的任意一个。其余 6 个工具（Wikipedia、arXiv、HN、Stack Exchange、Crossref、fetch_url）都可以在没有密钥的情况下使用。

Stack Exchange 返回 400 Bad Request

如果你配置了自定义的 filter 参数，API 会拒绝未知的 filter ID。请使用默认过滤器（省略该参数即可）——它返回的字段比你需要的更多，但一切都能正常工作。本服务器使用的正是默认值。

服务器首次启动时崩溃

请在 stderr 中查看实际的 traceback。常见原因是 Python 版本低于 3.10。请用 python3 --version 检查。

速率限制

每个无需密钥的 API 都有自己的限制。如果遇到限流：

• Wikipedia：约 200 次请求/分钟，请用真实的 User-Agent 标识自己（本服务器会发送）

• arXiv：未认证请求约 1 次/3 秒，请放慢请求

• Hacker News Algolia：有 API key 时 10k 次/小时，无 key 时 5k 次/小时

• Stack Exchange：无 key 时 300 次/天（对研究会话来说绰绰有余）

• Crossref：请在 User-Agent 中加入 mailto（本服务器已添加），之后便可在 polite pool 中无限使用

开发

项目结构

web-research-mcp/
├── bin/
│   └── web-research-mcp          # Launcher: venv bootstrap + exec
├── src/web_research/
│   ├── __init__.py
│   ├── server.py                  # MCPServer + 7 @app.tool functions
│   └── providers.py               # 7 search backends + Result dataclass
├── tests/
│   └── e2e_protocol.py            # Real subprocess JSON-RPC test
├── web-research.env.example       # API key template
├── pyproject.toml                 # PEP 621, uv-installable
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore

添加新工具

1. 在 providers.py 中添加一个 async 函数：

   async def search_my_source(query: str, max_results: int, client: httpx.AsyncClient) -> list[Result]:
       try:
           # ... your HTTP call ...
       except Exception as e:
           print(f"[my_source] error: {e}", flush=True)
           return []
       return [Result(title=..., url=..., snippet=..., source="my_source")]

2. 在 server.py 中注册它：

   @app.tool(name="search_my_source", description="...", annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
   async def search_my_source(query: Annotated[str, Field(description="Search query")], max_results: Annotated[int, Field(ge=1, le=10, default=5)] = 5) -> str:
       async with await _new_client() as client:
           res = await providers.search_my_source(query, max_results, client)
       return _format_results(query, res, "my_source") if res else f"No my_source results for: {query}"

3. 在 tests/e2e_protocol.py 中添加一个真实环境运行的测试用例。

4. 更新 README 的 Tools 部分。

代码风格

• Python 3.10+，async 优先

• 处处有类型注解；让 Pydantic 推导出 MCP JSON schema

• 每个 provider 都用 try/except 包裹网络调用，并降级为 []

• 每次调用都新建 HTTP 客户端（_new_client()）——在 stdio 模式下不要跨调用共享

参与贡献

欢迎提交 PR。在提交之前：

1. 在真实安装环境中运行 e2e 测试：.venv/bin/python tests/e2e_protocol.py

2. 为任何新增工具添加测试用例

3. 保持 providers.py 与 MCP 特定的类型无关——它应当能作为普通 Python 模块复用

4. 不要引入无头浏览器或代理轮换等依赖——那会违背项目的基本主张

如果改动较大，请先开一个 issue。

许可证

MIT —— 参见 LICENSE。

致谢

• 基于 Model Context Protocol 构建（Anthropic 出品）

• 使用 Jina Reader 获取干净页面

• 搜索 API：Brave、Tavily、Wikipedia、arXiv、Crossref、Hacker News Algolia、Stack Exchange