Paper Distill MCP

📚 Paper Distill MCP Server

Academic paper search, intelligent curation, and multi-platform delivery — built on the Model Context Protocol.

Compatible with all MCP clients: Claude Desktop, Claude Code, Cursor, Trae, Codex CLI, Gemini CLI, OpenClaw, VS Code, Zed, and more.

⚠️ Early development stage. Many features are still being validated and may contain bugs or instabilities. Feedback and bug reports are warmly welcome!

---

✨ Features

• 🔍 11-source parallel search — OpenAlex, Semantic Scholar, PubMed, arXiv, Papers with Code, CrossRef, Europe PMC, bioRxiv, DBLP, CORE, Unpaywall
• 🤖 Adaptive AI delivery — the agent tracks your evolving research interests and automatically refines search keywords and recommendations over time
• 📊 4-dimensional weighted ranking — relevance × recency × impact × novelty, fully customizable weights
• 👥 Dual-AI blind review — two AI reviewers independently shortlist papers; a chief reviewer synthesizes a final push/overflow/discard decision (optional)
• 🧹 Scraper delegation — offload abstract extraction to a low-cost agent or API to cut token spend significantly
• 🌐 Personal paper library site — Astro + Vercel auto-deploy; site updates within 30 seconds of each push
• 📬 Multi-platform delivery — Telegram / Discord / Feishu / WeCom
• 📦 Zotero integration — save papers to Zotero with one command
• 📝 Obsidian integration — auto-generate paper note cards with Zotero backlinks; supports summary and template modes

---

🚀 Quick Install

uvx paper-distill-mcp

That's it. Your AI client will discover all tools automatically. No API keys required for basic paper search.

No uv? → curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv

Other installation methods (pip / Homebrew / Docker / source)

pip:

pip install paper-distill-mcp

Homebrew:

brew tap Eclipse-Cj/tap

brew install paper-distill-mcp

Docker:

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

From source (developers):

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 .

---

🔗 Connecting to AI Clients

Claude Desktop

Add to 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

Or add to .mcp.json:

{

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

Codex CLI (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.paper-distill]

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

Gemini CLI (Google)

Add to ~/.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

To remove: mcporter config remove paper-distill

OpenClaw — install from source

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

To remove: rm -rf ~/.openclaw/tools/paper-distill-mcp && mcporter config remove paper-distill

Other clients (Cursor, VS Code, Windsurf, Zed, Trae)

Same JSON config, different config file paths:

HTTP transport (remote / hosted)

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

---

🎯 Getting Started

After connecting your client, tell the agent "initialize paper-distill". It will call setup() and walk you through:

1. Research topics — describe your interests in plain language; the AI extracts keywords
2. Delivery platform — set up Telegram / Discord / Feishu / WeCom (optional)
3. Paper library site — build a personal paper library that updates automatically (optional)
4. Scraper delegate — point to a low-cost agent or API for abstract extraction (recommended)
5. Preferences — paper count, ranking weights, review mode, etc.
6. First search — pool_refresh() populates the paper pool

All settings can be updated at any time through conversation:

• "Push 8 papers next time"
• "Add a new topic: RAG retrieval"
• "Enable dual-AI blind review"
• "Increase recency weight"

---

⚙️ Configuration Reference

All parameters are set via configure() or add_topic() — no manual file editing needed.

Research Topics (add_topic / manage_topics)

Paper Count & Review (configure)

💡 Dual blind review: two independent AI reviewers each shortlist papers; a chief reviewer makes the final push/overflow/discard call. Papers that don't make the cut are held for the next cycle rather than discarded. Enable with configure(review_mode="dual").

Ranking Weights (configure)

Controls paper scoring. The four weights should sum to approximately 1.0.

Example: "Prioritize recent papers" → configure(w_recency=0.35, w_relevance=0.40)

Scraper / Abstract Extraction Delegate (configure)

Abstract extraction is the most token-intensive step. It runs on the main agent by default, but can be delegated to a cheaper model to cut costs significantly.

🔧 Strongly recommended: for 30+ papers, frontier model costs add up fast. A $0.14/M-token model handles extraction just as well. Set this with configure(summarizer="scraper").

Paper Pool & Scan Batches (configure)

pool_refresh() searches all 11 APIs and fills the pool. The pool is then split into batches for daily AI review — avoiding a single 60+ paper dump.

• scan_batches=2 (default): review first half on day 1, second half on day 2, finalize on day 3
• scan_batches=3: review one-third per day, finalize on day 4

When all batches are reviewed, the pool is exhausted and the next run triggers a fresh API search automatically.

Delivery Platforms (Environment Variables)

⚠️ Important: set environment variables in the MCP client config env field, not as system environment variables. Otherwise send_push() cannot access the webhook URL and the AI may generate scripts that call webhooks directly, causing encoding issues.

Config example (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" } } } }

Restart the MCP client after editing the config.

Push message format (fixed):

1. Paper Title (Year)

Journal Name

• One-sentence summary
• Why it was selected https://doi.org/...

Paper Library Site (configure)

Personal paper library website, auto-updated on every push. Built on Astro + Vercel (free tier).

Setup steps (the AI agent will guide you):

1. Create a repo from the paper-library-template
2. Connect to Vercel and deploy
3. Create a deploy hook in Vercel (Settings > Git > Deploy Hooks)
4. Tell the agent the hook URL → saved via configure(site_deploy_hook=...)

After setup, every finalize_review() call pushes the digest JSON to the site repo and triggers a Vercel rebuild. The site updates in ~30 seconds.

Zotero Integration

Save papers to Zotero with one command. Requires a Zotero account and API key.

Getting credentials:

1. API Key: go to zotero.org/settings/keys/new → check "Allow library access" + "Allow write access" → Save Key
2. Library ID: go to zotero.org/settings/keys → your userID is shown at the top

Add to MCP client config:

{

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

After setup, reply collect 1 3 after a push to save papers 1 and 3 to Zotero, automatically sorted into per-topic folders.

All Environment Variables

| DEEPSEEK_API_KEY | Enhanced sear