Paper Distill MCP

📚 Paper Distill MCP 服务

基于模型上下文协议构建的学术论文搜索、智能筛选和多平台推送工具。

兼容所有 MCP 客户端：Claude Desktop、Claude Code、Cursor、Trae、Codex CLI、Gemini CLI、OpenClaw、VS Code、Zed 等。

⚠️ 目前仍处于早期开发阶段。 许多功能仍在验证中，可能存在错误或不稳定之处。欢迎反馈和提交错误报告！

✨ 功能

• 🔍 11 个来源并行搜索 — OpenAlex、Semantic Scholar、PubMed、arXiv、Papers with Code、CrossRef、Europe PMC、bioRxiv、DBLP、CORE、Unpaywall
• 🤖 自适应 AI 推送 — Agent 会追踪你不断变化的研究兴趣，并随时间自动优化搜索关键词和推荐
• 📊 四维加权排序 — 相关性 × 时效性 × 影响力 × 新颖性，权重完全可自定义
• 👥 双 AI 盲审 — 两位 AI 审稿人独立筛选论文；首席审稿人综合后，做出最终的推送／候补／舍弃决定（可选）
• 🧹 委托抓取 — 将摘要提取工作交给低成本 Agent 或 API，大幅减少 token 开销
• 🌐 个人论文库网站 — 使用 Astro + Vercel 自动部署；每次推送后，网站会在 30 秒内更新
• 📬 多平台推送 — Telegram / Discord / Feishu / WeCom
• 📦 Zotero 集成 — 通过一条命令将论文保存到 Zotero
• 📝 Obsidian 集成 — 自动生成带 Zotero 双向链接的论文笔记卡片；支持摘要和模板模式

🚀 快速安装

uvx paper-distill-mcp

就这么简单。你的 AI 客户端会自动发现所有工具。基本论文搜索无需 API 密钥。

没有 uv？→ curl -LsSf https://astral.sh/uv/install.sh | sh 或 brew install uv

pip install paper-distill-mcp

brew tap Eclipse-Cj/tap
brew install paper-distill-mcp

docker run -i --rm ghcr.io/eclipse-cj/paper-distill-mcp

git clone https://github.com/Eclipse-Cj/paper-distill-mcp.git
cd paper-distill-mcp
python3 -m venv .venv && .venv/bin/pip install --upgrade pip && .venv/bin/pip install -e .

🔗 连接 AI 客户端

Claude Desktop

添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "paper-distill": {
      "command": "uvx",
      "args": ["paper-distill-mcp"]
    }
  }
}

Claude Code

claude mcp add paper-distill -- uvx paper-distill-mcp

或添加到 .mcp.json：

{
  "mcpServers": {
    "paper-distill": {
      "command": "uvx",
      "args": ["paper-distill-mcp"]
    }
  }
}

Codex CLI（OpenAI）

添加到 ~/.codex/config.toml：

[mcp_servers.paper-distill]
command = "uvx"
args = ["paper-distill-mcp"]

Gemini CLI（Google）

添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "paper-distill": {
      "command": "uvx",
      "args": ["paper-distill-mcp"]
    }
  }
}

OpenClaw

mcporter config add paper-distill --command uvx --scope home -- paper-distill-mcp
mcporter list  # verify

移除方式：mcporter config remove paper-distill

git clone https://github.com/Eclipse-Cj/paper-distill-mcp.git ~/.openclaw/tools/paper-distill-mcp
cd ~/.openclaw/tools/paper-distill-mcp
uv venv .venv && uv pip install .
mcporter config add paper-distill \
  --command ~/.openclaw/tools/paper-distill-mcp/.venv/bin/python3 \
  --scope home \
  -- -m mcp_server.server
mcporter list

其他客户端（Cursor、VS Code、Windsurf、Zed、Trae）

JSON 配置相同，但配置文件路径不同：

HTTP 传输（远程／托管）

paper-distill-mcp --transport http --port 8765

🎯 快速开始

连接客户端后，告诉 Agent "initialize paper-distill"。它会调用 setup() 并引导你完成以下步骤：

1. 研究主题 — 用通俗语言描述你的兴趣；AI 会提取关键词
2. 推送平台 — 设置 Telegram / Discord / Feishu / WeCom（可选）
3. 论文库网站 — 构建个人论文库，并自动更新（可选）
4. 抓取委托方 — 指定低成本 Agent 或 API 来提取摘要（推荐）
5. 偏好设置 — 论文数量、排名权重、评审模式等
6. 首次搜索 — pool_refresh() 会填充论文池

随时可以通过对话更新所有设置：

• “下次推送 8 篇论文”
• “添加一个新主题：RAG 检索”
• “启用双 AI 盲审”
• “提高时效性权重”

⚙️ 配置参考

所有参数都通过 configure() 或 add_topic() 设置，无需手动编辑文件。

研究主题（add_topic / manage_topics）

论文数量与评审（configure）

💡 双盲评审：两位独立的 AI 评审者分别筛选论文；首席评审者决定最终推送、超额保留或丢弃哪些论文。未入选的论文会保留到下一轮，而不是丢弃。使用 configure(review_mode="dual") 启用。

排名权重（configure）

用于控制论文评分。四项权重之和应约为 1.0。

示例：“优先推荐近期论文” → configure(w_recency=0.35, w_relevance=0.40)

抓取器 / 摘要提取委托方（configure）

提取摘要是最耗 Token 的步骤。默认由主 Agent 执行，但可以委托给成本更低的模型，大幅降低费用。

🔧 强烈推荐：处理 30 篇以上论文时，前沿模型的成本会迅速增加。一个每百万 Token 仅需 $0.14 的模型就能胜任摘要提取。使用 configure(summarizer="scraper") 设置。

论文池与扫描批次（configure）

pool_refresh() 会搜索全部 11 个 API 并填充论文池。随后，论文池会拆分为多个批次，供 AI 每日审阅，避免一次性倾倒 60 多篇论文。

• scan_batches=2（默认）：第 1 天审阅前半部分，第 2 天审阅后半部分，第 3 天完成整理
• scan_batches=3：每天审阅三分之一，第 4 天完成整理

审阅完所有批次后，论文池即告用尽，下次运行时会自动触发新一轮 API 搜索。

推送平台（环境变量）

⚠️ 重要：请在 MCP 客户端配置的 env 字段中设置环境变量，而不是将其设为系统环境变量。否则，send_push() 无法访问 Webhook URL，AI 可能会生成直接调用 Webhook 的脚本，导致编码问题。

配置示例（WeCom + Claude Desktop）：

{
  "mcpServers": {
    "paper-distill": {
      "command": "uvx",
      "args": ["paper-distill-mcp"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY"
      }
    }
  }
}

编辑配置后，重启 MCP 客户端。

推送消息格式（固定）：

1. Paper Title (Year)
   Journal Name
   - One-sentence summary
   - Why it was selected
   https://doi.org/...

论文库网站（configure）

个人论文库网站，每次推送时自动更新。基于 Astro + Vercel 构建（免费套餐）。

设置步骤（AI Agent 会引导你）：

1. 从 paper-library-template 创建仓库
2. 连接到 Vercel 并部署
3. 在 Vercel 中创建部署 Hook（Settings > Git > Deploy Hooks）
4. 将 Hook URL 告诉 Agent → 通过 configure(site_deploy_hook=...) 保存

设置完成后，每次调用 finalize_review() 都会将摘要 JSON 推送到网站仓库并触发 Vercel 重建。网站会在约 30 秒内更新。

Zotero 集成

使用一条命令即可将论文保存到 Zotero。需要 Zotero 账户和 API 密钥。

获取凭据：

1. API 密钥：前往 zotero.org/settings/keys/new → 勾选“Allow library access” + “Allow write access” → 保存密钥
2. Library ID：前往 zotero.org/settings/keys → 你的 userID 显示在页面顶部

添加到 MCP 客户端配置：

{
  "mcpServers": {
    "paper-distill": {
      "command": "uvx",
      "args": ["paper-distill-mcp"],
      "env": {
        "ZOTERO_LIBRARY_ID": "your userID",
        "ZOTERO_API_KEY": "your API key"
      }
    }
  }
}

设置完成后，推送后回复 collect 1 3，即可将第 1 篇和第 3 篇论文保存到 Zotero，并自动按主题归入文件夹。

所有环境变量

🛠️ 工具（共 19 个）

设置与配置

搜索与整理

每日工作流（论文池模式）

会话与输出

🏗️ 架构

AI client (Claude Code / Codex CLI / Gemini CLI / Cursor / ...)
    ↓ MCP (stdio or HTTP)
paper-distill-mcp
    ├── search/         — 11-source academic search (with OA full-text enrichment)
    ├── curate/         — scoring + deduplication
    ├── generate/       — output (JSONL, Obsidian, site)
    ├── bot/            — push formatting (4 platforms)
    └── integrations/   — Zotero API

此服务不会在内部调用任何大模型。搜索、排序和去重都是纯数据操作。智能由你的 AI 客户端提供。

📖 付费论文与开放获取

系统默认搜索所有论文（包括订阅期刊），并通过以下方式尽可能获取免费全文：

1. CORE — 全球最大的开放获取聚合平台（2 亿多篇论文），收录来自机构知识库的作者自存档版本
2. Unpaywall — 合并搜索结果后，通过 DOI 自动查找合法的免费 PDF（预印本、绿色开放获取、作者版本）

对于没有免费版本的论文，系统会返回 DOI 链接。如果你可以使用机构 VPN，连接后点击 DOI 链接通常就足够了——出版商会根据 IP 识别你的机构。

open_access_url 优先级：arXiv > CORE > Unpaywall > OpenAlex > Semantic Scholar > Papers with Code

❓ 常见问题

审核阶段卡住 / 30 多分钟没有响应

症状：prepare_review() 生成的审核提示词导致 AI 客户端卡住或超时。

原因：论文池中的候选论文太多（例如 80–100 篇），导致提示词超出客户端的上下文窗口或输出令牌限制。VS Code Copilot 和一些 IDE 插件的上下文容量有限。

解决方案（任选其一）：

1. 增大 scan_batches（推荐）——将论文池拆分为更多批次：

   configure(scan_batches=5)
   

2. 减少主题或关键词——主题越少 → 搜索结果越少 → 论文池越小。
3. 改用上下文容量更大的客户端——Claude Code（200k）、Claude Desktop（200k）或 Cursor 更适合处理较长的提示词。

安装错误：Requires-Python >=3.10

需要 Python 3.10 或更高版本。macOS 默认自带 Python 3.9——请使用 brew install [email protected] 安装较新版本，或使用 uv。

Docker 镜像拉取失败（中国大陆）

中国大陆无法访问 ghcr.io。请使用 pip 和中国镜像：

pip install paper-distill-mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

🧑‍💻 开发

git clone https://github.com/Eclipse-Cj/paper-distill-mcp.git
cd paper-distill-mcp
python3 -m venv .venv && .venv/bin/pip install --upgrade pip && .venv/bin/pip install -e .
python tests/test_mcp_smoke.py   # 9 tests, no network required

📄 许可证

本项目采用 AGPL-3.0 许可证。详情请参阅 LICENSE。

禁止未经授权的商业使用。 如需咨询商业许可，请联系作者。

📬 联系方式

• 电子邮件：[email protected]
• GitHub Issues：Eclipse-Cj/paper-distill-mcp/issues

欢迎提交错误报告和功能请求。本项目目前处于积极的早期开发阶段——感谢你的耐心与支持 🙏