mcp-web-research

@opafex/mcp-web-research

用于网络研究的 MCP 服务——搜索网络、将网页提取为整洁文本、从网页中提取指定章节、并排比较网页，以及执行两阶段的“先搜索，再阅读热门结果”流程。

不涉及大模型：research_topic 和 compare_pages 只整理提取出的文本，不会生成文本。每次抓取网页都会经过 SSRF 检查，包括每一跳重定向。

搜索使用 Brave Search API（提供免费套餐）。没有密钥时，四个网页工具仍可使用，两个搜索工具则会报错并告知需要设置哪个变量。

安装

npx -y @opafex/mcp-web-research

需要 Node.js 20+。无需安装其他依赖。

快速开始

Claude Code

claude mcp add web-research -e BRAVE_SEARCH_API_KEY=your-key -- npx -y @opafex/mcp-web-research

或者将其添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "web-research": {
      "command": "npx",
      "args": ["-y", "@opafex/mcp-web-research"],
      "env": {
        "BRAVE_SEARCH_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop

将相同配置块添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "web-research": {
      "command": "npx",
      "args": ["-y", "@opafex/mcp-web-research"],
      "env": {
        "BRAVE_SEARCH_API_KEY": "your-key"
      }
    }
  }
}

省略 BRAVE_SEARCH_API_KEY，即可仅使用网页工具。

工具

web_search

未通过 SSRF 检查（见下文）的结果 URL 会在返回前被剔除。

[
  {
    "title": "Model Context Protocol",
    "url": "https://modelcontextprotocol.io/",
    "snippet": "An open protocol that enables seamless integration between LLM applications and external data sources and tools."
  }
]

fetch_webpage

脚本、样式、<nav> 和 <footer> 会被移除。如果页面经由重定向访问，则会包含 finalUrl。

{
  "title": "Example Domain",
  "text": "Example Domain\nThis domain is for use in illustrative examples in documents.",
  "url": "http://example.com/",
  "fetchedAt": "2026-10-24T12:00:00.000Z"
}

research_topic

关键要点是提及主题词的句子，每个来源最多五句。无法抓取的来源会改用其搜索摘要。

extract_structured_data

对于每个字段，返回首条提及该字段的行及其后的十行，最多 1,000 个字符；若未找到，则返回 No "<field>" section found on page.。这是基于标题的匹配，不是架构提取器。

compare_pages

抓取失败的页面会列出 "(fetch failed)" 和失败原因；其他页面仍会进行比较。

资源

搜索提供方

关于 DuckDuckGo 选项。 它会解析 html.duckduckgo.com 的结果页面。这不是 API：DuckDuckGo 一旦更改标记，就会导致它失效；它可能受到速率限制或被拦截，而且 DuckDuckGo 的条款不允许自动查询。它会发送此服务真实的用户代理，而不是伪装成浏览器，这使其更容易被拦截。保留此选项供个人实验使用；如果启用，您有责任遵守 DuckDuckGo 的条款。对于任何依赖的用途，请使用 Brave。

环境变量

安全性

页面工具会从服务运行所在的机器上抓取模型指定的 URL。若没有防护，该机器的内部网络和云元数据服务都可能通过一次工具调用被访问（服务端请求伪造）。每次抓取前都会进行检查，遇到以下情况时将拒绝请求：

• 协议不是 http 或 https；
• 主机名是 localhost、*.localhost 或云元数据名称（metadata.google.internal）；
• 主机名是非公网范围内的字面 IP 地址——IPv4，或带方括号的 IPv6。特殊的 IPv4 写法（http://2130706433/、http://0x7f.1/）会在检查前进行标准化；
• 主机名解析出的任何地址（IPv4 A 记录或 IPv6 AAAA 记录）都位于非公网范围内。存在一条公网 A 记录，并不能使私有 AAAA 记录变得安全；
• 主机名无法解析。**检查失败时默认拒绝：**无法检查的地址不会被抓取。

屏蔽范围：

重定向会手动跟进，并重新检查每一跳——最多 5 跳。若公网网页重定向到 http://169.254.169.254/，系统会在发出第二个请求前拒绝访问。搜索结果 URL 也会经过检查，不符合要求的会被丢弃。

已知限制——DNS 重绑定。 检查时会解析主机名，随后 fetch 会再次解析该主机名以建立连接。TTL 极短的恶意 DNS 服务器可能会在两次查询中返回不同的地址。若要消除这一风险，就必须将连接固定到已检查的地址，而 Node 内置的 fetch 无法在不引入额外依赖的情况下实现这一点。如果此服务运行在具有敏感内部服务的环境中，还应在网络层面限制其可访问范围（容器网络策略、出口防火墙）。

限制

• 仅限文本。 页面必须是 text/*、application/xhtml+xml 或 application/json；PDF、图片和其他二进制类型会被拒绝。
• 不执行 JavaScript。 页面会按原样抓取。客户端渲染的内容不会包含在结果中。
• 基于正则表达式解析 HTML。 速度快且无需依赖，但并非完整的 HTML 解析器；特殊标记可能会泄漏到文本中。
• 启发式提取。 research_topic 的关键要点和 extract_structured_data 的分节采用关键词匹配，而非语义理解。
• 内存缓存，按进程隔离，重启后会丢失。
• 假定使用 UTF-8。 其他编码的页面可能会被替换字符解码。
• 不是爬虫。 不处理 robots.txt；只抓取收到的 URL。

开发

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (no build needed)
npm test         # Run tests (no network — fetch and DNS are faked)
npm start        # Run compiled server

贡献

发现错误或有功能建议？提交议题。

欢迎提交拉取请求——请参阅主代码库了解开发环境配置。

许可证

MIT——请参阅 LICENSE。