mcp-research

一个提供网络研究工具的独立 MCP (Model Context Protocol) 服务器。为 AI 助手提供三个经过实战检验的工具：搜索网络、获取并转换为 Markdown 页面，以及运行复合多源研究——所有这些都通过 MCP stdio 协议实现。

工具

所有工具均为只读——它们仅获取并转换公共网络内容，绝不修改任何内容。

安装

pip install mcp-research

或者直接使用 uvx 运行（无需安装）：

uvx mcp-research

配置

所有配置均通过环境变量完成——无需配置文件。

在 Claude Code 中使用

添加到您的 Claude Code MCP 配置中（~/.claude/settings.json 或项目 .mcp.json）：

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA...",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

在 Claude Desktop 中使用

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    }
  }
}

工具详情

web_search

web_search(query, max_results=5, summarize=False, auto_fetch_top=False)

使用三层级联搜索网络以实现最大可靠性：

1. Brave Search API — 快速、高质量（需要 BRAVE_API_KEY）

2. DuckDuckGo 库 — 无需 API 密钥，在速率限制时重试

3. DuckDuckGo HTML 抓取器 — 最后的回退手段

选项：

• summarize: 使用 Ollama 总结结果（需要运行 Ollama）

• auto_fetch_top: 同时获取并返回顶部结果的完整内容

fetch_url

fetch_url(url, summarize=False, max_chars=50000)

获取 URL 并将其转换为整洁的 Markdown：

• SSRF 防护: 阻止 localhost、私有 IP、非 HTTP 协议

• 智能重试: 在 429/5xx 错误时进行指数退避，逐跳重定向验证

• 24 小时缓存: SHA-256 键值，可配置 TTL

• 内容支持: HTML → Markdown，JSON → 代码块，二进制 → 拒绝

• 智能截断: 在标题/段落边界处断开，而不是在文本中间断开

research

research(query, depth="standard", context="")

复合研究流水线：

1. 查询重写 — Ollama 将您的问题优化为搜索关键词

2. 网络搜索 — 查找相关页面（支持零结果重试扩展）

3. 并行获取 — 并发获取前 N 个页面

4. 摘要 — Ollama 总结每个页面

5. 综合 — Ollama 生成最终的带引用答案

深度级别：

所有步骤在没有 Ollama 的情况下都会优雅降级——您仍然可以获得搜索结果和原始页面内容。

开发

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e .
python -m mcp_research

许可证

MIT