Maibaamcrawler

mcp-research

用于网页研究、学术论文、Twitter/X、YouTube 和文件导入的 MCP 服务。为 AI 助手提供 8 个工具，全部通过 MCP stdio 协议运行。包含用于机构访问的凭据库、CAPTCHA 检测和节省令牌的输出。

工具

工具	描述
web_search	三级搜索级联：Brave API → DuckDuckGo → HTML 抓取器
fetch_url	获取任意 URL → 转换为简洁的 Markdown，并提供 SSRF 防护和 24h 缓存
research	复合工作流：查询改写 → 搜索 → 并行获取 → 总结 → 综合
youtube_essence	YouTube 视频 → 转录文本、摘要、要点、章节、引文
deep_ingest	从文件中提取文本：PDF、DOCX、XLSX、PPTX、音频、视频、图像
academic_lookup	解析 DOI / ArXiv / PubMed → 通过机构访问获取元数据和全文
twitter_extract	从 X.com/Twitter 提取推文和推文串
vault_status	显示已加载的凭据配置和依赖项状态（绝不暴露机密）

所有工具均为只读——它们获取并转换内容，不会修改任何内容。

安装

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..."
      }
    }
  }
}

配置

所有配置均通过环境变量进行，无需配置文件（可选的凭据库除外）。

变量	默认值	描述
BRAVE_API_KEY	(空)	Brave Search API 密钥。若未设置，则回退到 DuckDuckGo。
OLLAMA_URL	http://localhost:11434	用于总结和综合的 Ollama 端点。设为空即可停用。
OLLAMA_MODEL	qwen2.5:14b	用于总结和综合的模型。
MCP_RESEARCH_CACHE_DIR	~/.mcp-research/cache/	URL 获取缓存目录。
MCP_RESEARCH_CACHE_TTL	24	缓存 TTL（小时）。
MCP_RESEARCH_LOG_DIR	~/.mcp-research/logs/	搜索日志目录（NDJSON）。
MCP_RESEARCH_MAX_RESULTS	10	默认最大搜索结果数。
MCP_RESEARCH_VAULT_FILE	~/.mcp-research/vault.yaml	凭据库文件路径。
MCP_RESEARCH_VAULT_HOT_RELOAD	true	文件变更时自动重新加载凭据库。
MCP_RESEARCH_SESSION_TTL	1800	会话空闲超时时间（秒）。

工具详情

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

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

• SSRF 防护：阻止 localhost、私有 IP 和非 HTTP 协议
• 智能重试：遇到 429/5xx 时采用指数退避，并逐跳验证重定向
• 24h 缓存：使用 SHA-256 作为键，TTL 可配置
• 内容支持：HTML → Markdown，JSON → 代码块，二进制内容 → 拒绝
• 智能截断：在标题或段落边界处截断，不会截断文本中间
• CAPTCHA 检测：标记 Cloudflare、hCaptcha、reCAPTCHA 和 Akamai 屏障
• 节省令牌：默认 15K 个字符（约 4K 个令牌），可通过 max_chars 调整

research

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

复合研究工作流：

1. 查询改写 — Ollama 将你的问题优化为搜索关键词
2. 网页搜索 — 查找相关页面（无结果时会扩展查询并重试）
3. 并行抓取 — 并发抓取排名靠前的 N 个页面
4. 总结 — Ollama 总结每个页面
5. 综合 — Ollama 生成最终的引用答案

深度级别：

深度	页面数	综合
quick	2	否
standard	5	是
deep	10	是

即使没有 Ollama，所有步骤也会优雅降级——你仍然可以获得搜索结果和页面内容。

youtube_essence

youtube_essence(url, mode="standard")

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

• 转录稿：自动字幕或 Whisper 转录（本地处理，保护隐私）
• 摘要：通过 Ollama 生成的 AI 摘要
• 要点：项目符号列出的核心内容
• 章节：带时间戳的片段
• 引言：值得关注的引述（深度模式）

模式：quick（简要总结）、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 令牌、API 密钥、基本身份验证、Cookie 存储
• 自动检测出版商（IEEE、Springer、Elsevier、ACM、Wiley、Nature、JSTOR 等）

twitter_extract

twitter_extract(url, include_thread=False)

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

1. yt-dlp（首选）— 配合 Cookie 存储可进行身份验证访问
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：

工具	默认输出	覆盖方式
fetch_url	约 15K 个字符（约 4K 个 Token）	max_chars 参数
research	每个来源约 500 个 Token	优先输出摘要，而非原始内容
academic_lookup	约 10K 个字符的全文	截断时会附带说明
deep_ingest	15 个文件，每个文件摘录 300 个字符	max_files 参数
youtube_essence	3K 字符的转录稿摘录	结果对象中包含完整转录稿

安全性与稳健性

• SSRF 防护：在每一跳中拦截 localhost、私有 IP、链路本地地址和非 HTTP 协议
• 验证码检测：识别 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 和空闲会话回收
• 验证码检测：识别 Cloudflare、hCaptcha、reCAPTCHA、Akamai、DDoS-Guard 和通用机器人防护页
• 学术资料查询：解析 DOI/ArXiv/PubMed，通过保险库获取 Crossref 元数据和机构全文
• Twitter/X 提取：通过 yt-dlp、API v2 和基于 Cookie 的方式访问，支持帖子串
• 提高令牌效率：默认限制输出长度（fetch 约 4K 个令牌，每个研究来源约 500 个令牌），以保留 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