mcp-research

用于网络研究、学术论文、Twitter/X、YouTube 和文件提取的 MCP 服务器。为 AI 助手提供八种工具——全部通过 MCP stdio 协议实现。包含用于机构访问的凭据库、CAPTCHA 检测以及节省 Token 的输出功能。

工具

所有工具均为只读——它们仅获取和转换内容，从不进行任何修改。

Related MCP server: Research Powerpack MCP

安装

pip install mcp-research

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

uvx mcp-research

可选扩展：

pip install 'mcp-research[twitter]' # yt-dlp for Twitter extraction
pip install 'mcp-research[youtube]' # yt-dlp + faster-whisper for YouTube
pip install 'mcp-research[academic]' # PyPDF2 for academic PDFs
pip install 'mcp-research[ingest]' # PDF, DOCX, XLSX, PPTX, audio support
pip install 'mcp-research[all]' # everything

检查您的设置：

mcp-research doctor

与 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)

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

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=15000)

获取 URL 并将其转换为干净的 Markdown：

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

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

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

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

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

• CAPTCHA 检测: 标记 Cloudflare、hCaptcha、reCAPTCHA、Akamai 防火墙

• Token 高效: 默认 15K 字符（约 4K Token），可通过 max_chars 调整

research

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

复合研究流水线：

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

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

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

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

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

深度级别：

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

youtube_essence

youtube_essence(url, mode="standard")

从 YouTube 视频中提取结构化内容：

• 字幕: 自动字幕或 Whisper 转录（本地、私有）

• 摘要: 通过 Ollama 进行 AI 摘要

• 要点: 项目符号总结

• 章节: 带时间戳的片段

• 引用: 值得注意的引语（深度模式）

模式：quick (TL;DR), standard (+ 章节), deep (+ 引用)

需要 yt-dlp。可选：用于纯音频视频的 faster-whisper，用于媒体提取的 ffmpeg。

deep_ingest

deep_ingest(path, include_types="", max_files=200, summarize=False)

从目录或单个文件中的文件中提取文本：

• 文本文件: .txt, .md, .json, .csv, 源代码等

• PDF: 通过 PyPDF2（可选依赖）

• Office: .docx, .xlsx, .pptx（可选依赖）

• 音频/视频: Whisper 转录（可选）

• 图像: 通过 Ollama 视觉模型进行 OCR（可选）

类型过滤器：text, pdf, audio, video, image, office

academic_lookup

academic_lookup(identifier, fetch_fulltext=True)

从多种标识符类型解析学术论文：

• DOI: 10.xxxx/... → Crossref 元数据 + 出版商重定向

• ArXiv: 2301.12345 → 摘要 + PDF

• PubMed: PMID → E-utilities 元数据 → DOI 链

• URL: 出版商页面检测

通过凭据库获取全文访问权限：

• EZproxy 重写（前缀和后缀模式）

• Bearer Token、API 密钥、基本认证、Cookie Jar

• 自动出版商检测（IEEE, Springer, Elsevier, ACM, Wiley, Nature, JSTOR 等）

twitter_extract

twitter_extract(url, include_thread=False)

使用级联策略从 X.com/Twitter 提取推文和推文串：

1. yt-dlp (主要) — 使用 Cookie Jar 进行认证访问

2. Twitter API v2 — 如果在凭据库中配置了 Bearer Token

3. HTML 获取 — 基于 Cookie 的最后手段

返回：文本、作者、时间戳、指标（点赞、转发、回复）、媒体 URL。

vault_status

vault_status()

显示已加载的凭据配置文件、匹配模式和认证类型——绝不泄露密钥。同时检查可选依赖项的可用性。

凭据库

创建 ~/.mcp-research/vault.yaml 以配置受保护源的认证：

version: 1
profiles:
 # University EZproxy for IEEE
 ieee-university:
 match: "*.ieee.org/**"
 ezproxy:
 base_url: "https://ezproxy.myuniversity.edu/login?url="
 mode: prefix

 # Springer via API key
 springer:
 match: "*.springer.com/**"
 auth:
 type: api_key
 header: "X-ApiKey"
 value: "${SPRINGER_API_KEY}"

 # X.com via browser cookies
 twitter:
 match: "*.x.com/**"
 auth:
 type: cookie_jar
 path: "${HOME}/.mcp-research/cookies/twitter.txt"

• ${VAR} 从环境变量解析——密钥绝不以明文存储

• 第一个匹配的配置文件生效（顺序很重要）

• 认证类型：bearer, basic, api_key, cookie_jar, headers

• EZproxy 模式：prefix（前缀基础 URL）或 suffix（域名重写）

• 热重载：凭据库文件更改会自动生效

Token 效率

所有工具默认生成紧凑的输出，以避免浪费 AI 上下文窗口的 Token：

安全与健壮性

• SSRF 防护: 在每一跳上阻止 localhost、私有 IP、链路本地地址、非 HTTP 协议

• CAPTCHA 检测: 识别 Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard 防火墙

• 输入验证: 大小限制、URL 验证、安全重定向跟踪

• 无 eval/exec: 无动态代码执行

• 凭据库安全: 密钥从环境变量解析，repr() 会屏蔽所有认证值

• 缓存隔离: 仅限所有者的目录权限 (0o700)

• 优雅降级: 缺失可选依赖不会导致崩溃——功能会通过清晰的消息降级

CLI

mcp-research serve # Run MCP stdio server (default)
mcp-research search "query" # Search the web
mcp-research fetch https://example.com # Fetch URL to markdown
mcp-research youtube https://youtu.be/... # Extract YouTube video
mcp-research ingest ./docs/ # Extract text from files
mcp-research academic "10.1109/..." # Resolve academic paper
mcp-research tweet https://x.com/.../123 # Extract tweet
mcp-research vault # Show vault profiles
mcp-research doctor # Check dependencies

开发

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e ".[all]"
pytest tests/ -v
python -m mcp_research

更新日志

v0.3.0

• 凭据库: ~/.mcp-research/vault.yaml YAML 配置，支持环境变量插值、Glob URL 匹配、EZproxy 重写、热重载

• 会话池: 具有凭据库认证注入、Cookie Jar 支持、空闲驱逐的按域名会话

• CAPTCHA 检测: 识别 Cloudflare, hCaptcha, reCAPTCHA, Akamai, DDoS-Guard, 通用机器人防火墙

• 学术查找: DOI/ArXiv/PubMed 解析、Crossref 元数据、通过凭据库进行机构全文访问

• Twitter/X 提取: yt-dlp, API v2, 以及支持推文串的基于 Cookie 的访问

• Token 效率: 默认输出上限（获取约 4K Token，每个研究源约 500 Token）以保留 AI 上下文

• Doctor 命令: mcp-research doctor 检查所有依赖项和配置

• Windows 编码修复: UTF-8 stdout/stderr 包装器防止 cp1252 崩溃

v0.2.0

• YouTube 精华: 字幕提取、AI 摘要、要点、章节、引用

• 深度提取: PDF, DOCX, XLSX, PPTX, 音频, 视频, 图像文本提取

• Ollama 集成: 查询重写、摘要、综合、视觉 OCR

• 搜索日志: 所有操作的 NDJSON 事件日志

• Brave Search: 支持 API 密钥的主要搜索层

v0.1.0

• 初始版本：3 个工具 (web_search, fetch_url, research)，SSRF 防护，缓存

许可证

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• academic_lookupA
• deep_ingestA
• fetch_urlA
• researchA
• twitter_extractA
• vault_statusA
• web_searchA
• youtube_essenceA