paper-distill-mcp 0.2.3

MCP server for academic paper search, curation, and multi-platform push

📚 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:

Client	Config path
Claude Desktop	claude_desktop_config.json
Trae	Settings → MCP → Add
Cursor	~/.cursor/mcp.json
VS Code	.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Zed	settings.json

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)

Parameter	Description	Default
key	Topic identifier (e.g. "llm-reasoning")	—
label	Display name (e.g. "LLM Reasoning")	—
keywords	Search keywords, 3–5 recommended	—
weight	Topic priority 0.0–1.0 (higher = more papers)	1.0
blocked	Temporarily disable without deleting	false

Paper Count & Review (configure)

Parameter	Options	Default	Description
paper_count_value	any integer	6	Papers per push
paper_count_mode	"at_most" / "at_least" / "exactly"	"at_most"	Count mode
picks_per_reviewer	any integer	5	Shortlist size per reviewer
review_mode	"single" / "dual"	"single"	Single AI or dual blind review
custom_focus	free text	""	Custom selection criteria

💡 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.

Parameter	Measures	Default
w_relevance	Keyword and topic match	0.55
w_recency	How recently the paper was published	0.20
w_impact	Citation count (log-normalized)	0.15
w_novelty	Whether this is the first appearance	0.10

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.

Parameter	Value	Description
summarizer	"self"	Main agent handles extraction (most expensive)
	agent name (e.g. "scraper")	Delegate to a low-cost sub-agent
	API URL	Call an external LLM API (DeepSeek, Ollama, etc.)

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

Parameter	Description	Default
scan_batches	Split the paper pool into N batches, reviewed over N+1 days	2 (3 days)

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)

Platform	Environment variables	platform value
Telegram	TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID	"telegram"
Discord	DISCORD_WEBHOOK_URL	"discord"
Feishu	FEISHU_WEBHOOK_URL	"feishu"
WeCom	WECOM_WEBHOOK_URL	"wecom"

⚠️ 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).

Parameter	Description
site_deploy_hook	Vercel deploy hook URL (triggers site rebuild)
site_repo_path	Local path to the paper-library repository

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

Variable	Description	Required
OPENALEX_EMAIL	Increases OpenAlex API rate limit; also used for Unpaywall	optional
CORE_API_KEY	CORE API key (free registration)	optional
DEEPSEEK_API_KEY	Enhanced search via DeepSeek	optional
ZOTERO_LIBRARY_ID + ZOTERO_API_KEY	Save papers to Zotero	optional
SITE_URL	Paper library website URL	optional
PAPER_DISTILL_DATA_DIR	Data directory	default: ~/.paper-distill/

---

🛠️ Tools (19 total)

Setup & Configuration

Tool	Description
setup()	First call — detects fresh install and returns guided initialization instructions
add_topic(key, label, keywords)	Add a research topic with search keywords
configure(...)	Update any setting: paper count, ranking weights, review mode, etc.

Search & Curation

Tool	Description
search_papers(query)	Parallel search across 11 sources
rank_papers(papers)	4-dimensional weighted scoring
filter_duplicates(papers)	Deduplicate against previously pushed papers

Daily Pipeline (paper pool mode)

Tool	Description
pool_refresh(topic?)	Search all 11 APIs and build the paper pool
prepare_summarize(custom_focus?)	Generate AI abstract extraction prompt
prepare_review(dual?)	Generate review prompt — AI makes push/overflow/discard decisions
finalize_review(selections)	Process AI decisions, update pool, output push message
pool_status()	Pool status: count, scan day, exhausted or not
collect(paper_indices)	Save papers to Zotero + generate Obsidian notes

Session & Output

Tool	Description
init_session	Detect delivery platform and load research context
load_session_context	Load historical research context
generate_digest(papers, date)	Generate output files (JSONL, site, Obsidian)
send_push(date, papers, platform)	Deliver to Telegram / Discord / Feishu / WeCom
collect_to_zotero(paper_ids)	Save to Zotero via DOI
manage_topics(action, topic)	List / disable / enable / reweight topics
ingest_research_context(text)	Inherit research context across sessions

---

🏗️ Architecture

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

The server does not call any LLM internally. Search, ranking, and deduplication are pure data operations. Intelligence comes from your AI client.

---

📖 Paywalled Papers & Open Access

The system searches all papers by default (including subscription journals) and maximizes free full-text access through:

1. CORE — world's largest OA aggregator (200M+ papers), covering author self-archived versions from institutional repositories
2. Unpaywall — after merging results, automatically looks up legal free PDFs via DOI (preprints, green OA, author versions)

For papers with no free version, the system returns a DOI link. If you have institutional VPN access, clicking the DOI link while connected is usually enough — publishers identify your institution by IP.

open_access_url priority: arXiv > CORE > Unpaywall > OpenAlex > Semantic Scholar > Papers with Code

---

❓ FAQ

Review stage hangs / no response for 30+ minutes

Symptom: the review prompt generated by prepare_review() causes the AI client to hang or time out.

Cause: too many candidate papers in the pool (e.g. 80–100), making the prompt exceed the client's context window or output token limit. VS Code Copilot and some IDE plugins have limited context capacity.

Solutions (pick one):

1. Increase scan_batches (recommended) — split the pool into more batches:

   configure(scan_batches=5)
   

2. Reduce topics or keywords — fewer topics → fewer search results → smaller pool.
3. Switch to a higher-context client — Claude Code (200k), Claude Desktop (200k), or Cursor handle long prompts better.

Install error: Requires-Python >=3.10

Python 3.10+ is required. macOS ships with Python 3.9 by default — install a newer version with brew install python@3.13 or use uv.

Docker image fails to pull (mainland China)

ghcr.io is blocked in mainland China. Use pip with a Chinese mirror:

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

---

🧑‍💻 Development

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

---

📄 License

This project is licensed under AGPL-3.0. See LICENSE for details.

Unauthorized commercial use is prohibited. For commercial licensing inquiries, contact the author.

---

📬 Contact

• Email: [e-mail]
• GitHub Issues: Eclipse-Cj/paper-distill-mcp/issues

Bug reports and feature requests are welcome. The project is in active early development — thank you for your patience and support 🙏