Paper Distill MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Paper Distill MCP Server Find recent papers on LLM reasoning and sync the top results to Zotero"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ 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
Related MCP server: Literature Review MCP Server
๐ Quick Install
uvx paper-distill-mcpThat'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 | shorbrew install uv
pip:
pip install paper-distill-mcpHomebrew:
brew tap Eclipse-Cj/tap
brew install paper-distill-mcpDocker:
docker run -i --rm ghcr.io/eclipse-cj/paper-distill-mcpFrom 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-mcpOr 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 # verifyTo remove:
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 listTo 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 |
|
Trae | Settings โ MCP โ Add |
Cursor |
|
VS Code |
|
Windsurf |
|
Zed |
|
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:
Research topics โ describe your interests in plain language; the AI extracts keywords
Delivery platform โ set up Telegram / Discord / Feishu / WeCom (optional)
Paper library site โ build a personal paper library that updates automatically (optional)
Scraper delegate โ point to a low-cost agent or API for abstract extraction (recommended)
Preferences โ paper count, ranking weights, review mode, etc.
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 |
| Topic identifier (e.g. | โ |
| Display name (e.g. | โ |
| Search keywords, 3โ5 recommended | โ |
| Topic priority 0.0โ1.0 (higher = more papers) |
|
| Temporarily disable without deleting |
|
Paper Count & Review (configure)
Parameter | Options | Default | Description |
| any integer |
| Papers per push |
|
|
| Count mode |
| any integer |
| Shortlist size per reviewer |
|
|
| Single AI or dual blind review |
| 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 |
| Keyword and topic match |
|
| How recently the paper was published |
|
| Citation count (log-normalized) |
|
| Whether this is the first appearance |
|
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 |
|
| Main agent handles extraction (most expensive) |
agent name (e.g. | 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 |
| Split the paper pool into N batches, reviewed over N+1 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 3scan_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 |
|
Telegram |
|
|
Discord |
|
|
Feishu |
|
|
WeCom |
|
|
โ ๏ธ Important: set environment variables in the MCP client config
envfield, not as system environment variables. Otherwisesend_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 |
| Vercel deploy hook URL (triggers site rebuild) |
| Local path to the paper-library repository |
Setup steps (the AI agent will guide you):
Create a repo from the paper-library-template
Connect to Vercel and deploy
Create a deploy hook in Vercel (Settings > Git > Deploy Hooks)
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:
API Key: go to zotero.org/settings/keys/new โ check "Allow library access" + "Allow write access" โ Save Key
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 |
| Increases OpenAlex API rate limit; also used for Unpaywall | optional |
| CORE API key (free registration) | optional |
| Enhanced search via DeepSeek | optional |
| Save papers to Zotero | optional |
| Paper library website URL | optional |
| Data directory | default: |
๐ ๏ธ Tools (19 total)
Setup & Configuration
Tool | Description |
| First call โ detects fresh install and returns guided initialization instructions |
| Add a research topic with search keywords |
| Update any setting: paper count, ranking weights, review mode, etc. |
Search & Curation
Tool | Description |
| Parallel search across 11 sources |
| 4-dimensional weighted scoring |
| Deduplicate against previously pushed papers |
Daily Pipeline (paper pool mode)
Tool | Description |
| Search all 11 APIs and build the paper pool |
| Generate AI abstract extraction prompt |
| Generate review prompt โ AI makes push/overflow/discard decisions |
| Process AI decisions, update pool, output push message |
| Pool status: count, scan day, exhausted or not |
| Save papers to Zotero + generate Obsidian notes |
Session & Output
Tool | Description |
| Detect delivery platform and load research context |
| Load historical research context |
| Generate output files (JSONL, site, Obsidian) |
| Deliver to Telegram / Discord / Feishu / WeCom |
| Save to Zotero via DOI |
| List / disable / enable / reweight topics |
| 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 APIThe 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:
CORE โ world's largest OA aggregator (200M+ papers), covering author self-archived versions from institutional repositories
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_urlpriority: 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):
Increase
scan_batches(recommended) โ split the pool into more batches:configure(scan_batches=5)Reduce topics or keywords โ fewer topics โ fewer search results โ smaller pool.
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: vertex.cj@gmail.com
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 ๐
Available Tools
19 toolsadd_topicB
Add a research topic for paper search.
Inputs: key (required), label (required), keywords (required), weight. Returns: object
collectA
Collect pushed papers to Zotero and optionally create Obsidian notes.
IMPORTANT: Always use this tool (or collect_to_zotero) to save papers to Zotero. NEVER call the Zotero API directly or generate scripts to do so.
Use after finalize_review. Paper indices refer to the latest push (1-based, e.g. "1,3" to collect papers 1 and 3).
Inputs: paper_indices (required), obsidian_mode. Returns: result
collect_to_zoteroA
Add papers to Zotero library by their IDs/DOIs.
IMPORTANT: Always use this tool to add papers to Zotero. NEVER call the Zotero Web API directly or generate scripts (PowerShell, curl, etc.) to do so โ that will result in incomplete metadata (missing titles, authors). This tool handles full metadata enrichment automatically.
Looks up papers in papers.jsonl, creates Zotero journal article items and maps them to collections based on topic tags.
Inputs: paper_ids (required). Returns: result
configureA
Update pipeline configuration.
All parameters are optional โ only provided values are changed.
Inputs: w_impact, w_novelty, w_recency, summarizer, +9 more. Returns: object
filter_duplicatesA
Remove papers already pushed (by DOI match against papers.jsonl).
Inputs: papers (required). Returns: result
finalize_reviewA
Process AI review decisions, update pool, and generate push output.
Takes the AI's review response (JSON with push/overflow/discard decisions), updates paper statuses in the pool, appends pushed papers to papers.jsonl, and returns formatted push message.
Inputs: selections (required), is_final. Returns: result
generate_digestB
Generate all daily output files (pushes.jsonl, papers.jsonl, Astro site JSON, Obsidian notes).
Inputs: date (required), papers (required), topics. Returns: object
ingest_research_contextA
Ingest research context from other AI conversations for cross-AI context inheritance.
Extracts keywords from the markdown text and appends to interests.jsonl. Use session_id to isolate different chat sessions (prevents context pollution when multiple OpenClaw/AI sessions run concurrently).
Inputs: markdown_text (required), search_now, session_id. Returns: object
init_sessionA
Initialize a research session. Call this first to set up push channels and load context.
Detects configured platforms, manages channels, and optionally loads previous research context. Returns session info for the AI client to present to the user.
IMPORTANT for AI clients:
NEVER call external APIs (Zotero, webhooks, etc.) directly or generate scripts (PowerShell, curl, Python) to do so. Always use the built-in tools (collect, collect_to_zotero, send_push, etc.). Direct API calls will result in incomplete data and encoding issues.
If multiple platforms are detected and no
platformis specified, the response will includeask_platformโ you MUST ask the user which platform to use, then call init_session again withplatform=<user_choice>.If only one platform is configured, it is auto-selected.
The
send_pushtool also accepts aplatformparameter, so the user can override per-push even after init.
Inputs: platform, session_id, load_context, channel_action. Returns: object
load_session_contextA
Load previous research context into current session.
Call this after init_session if user chose to load context. Returns accumulated keywords and summaries from interests.jsonl.
Inputs: session_id. Returns: object
manage_topicsC
Manage research topic preferences.
Inputs: action (required), topic, weight. Returns: object
pool_refreshA
Refresh the paper search pool by querying 9 academic APIs.
Call this when pool is exhausted or when adding a new research topic. Searches: OpenAlex, Semantic Scholar, PubMed, arXiv, Papers with Code, CrossRef, Europe PMC, bioRxiv, DBLP.
Inputs: topic. Returns: object
pool_statusA
Show current pool status: paper counts by status, scan day, topics searched.
Returns: Dict with total, by_status, scan_day, total_scan_days, exhausted, etc.
Inputs: no named parameters. Returns: object
prepare_reviewA
Prepare the review prompt for today's scan batch.
Returns a structured prompt listing candidate papers for the AI to review. The AI should respond with push/overflow/discard decisions in JSON format.
If pool is exhausted, returns "POOL_EXHAUSTED" โ call pool_refresh first.
Inputs: dual. Returns: result
prepare_summarizeA
Generate a summarization prompt for unsummarized papers in today's batch.
Returns a dict with:
prompt: the summarization prompt (structured fields to extract)
summarizer: who should process this prompt ("self", agent name, or API URL)
paper_count: how many papers need summarizing
If summarizer is NOT "self", the calling agent should delegate this prompt to the specified agent or API instead of processing it directly. This can save significant token costs.
Inputs: custom_focus. Returns: object
rank_papersB
Score and rank papers using 4-factor weighted formula.
Factors: relevance (0.55), recency (0.20), impact (0.15), novelty (0.10). Uses topic_prefs.json for relevance scoring and papers.jsonl for novelty detection.
Inputs: papers (required), top_n. Returns: result
search_papersA
Search academic papers across 9 sources (OpenAlex, Semantic Scholar, PubMed, arXiv, Papers with Code, CrossRef, Europe PMC, bioRxiv, DBLP).
Returns deduplicated, merged results sorted by cross-source hits + citation count. Each paper has: title, year, doi, authors, abstract, source, citation_count, etc.
Inputs: query (required), max_results. Returns: result
send_pushB
Format and send daily paper distill to a messaging platform.
Supported platforms: telegram, discord, feishu (้ฃไนฆ/Lark), wecom (ไผไธๅพฎไฟก webhook).
Inputs: date (required), papers (required), platform. Returns: result
setupA
Check setup status and guide first-time configuration.
Call this FIRST when starting a new session. Returns setup state and instructions for the AI client on what to ask the user.
If setup is complete, returns current config summary. If first run, returns step-by-step instructions for the AI to follow.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 19 tools
Most tools have distinct purposes, but 'collect' and 'collect_to_zotero' overlap in adding papers to Zotero. Descriptions help differentiate, but an agent might still misselect.
Tool names mostly follow a verb_noun pattern (e.g., add_topic, search_papers), but a few are single verbs (collect, configure) or have longer phrases (load_session_context). Still readable and predictable.
19 tools cover a complex research pipeline (search, review, collection, push) without being excessive. Each tool serves a clear step in the workflow.
The tool surface covers the full lifecycle: setup, session management, topic management, paper search, pool management, review, summarization, Zotero collection, and messaging push. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Research paper search with real citations and reference formatting for AI assistants
Related MCP Servers
- FlicenseCqualityBmaintenanceEnables academic literature management through PDF import, hybrid search, knowledge graph construction, and automated literature review generation. Combines full-text search with semantic vector search for comprehensive paper analysis.55-
- AlicenseNot gradedqualityDmaintenanceAn academic paper management tool that enables multi-source research searching, batch PDF analysis, and the generation of comprehensive, cross-literature reviews. It features intelligent token compression and quality evaluation to streamline the literature review workflow for researchers.58 npm25MIT
- AlicenseAqualityDmaintenanceA local academic tool that enables searching across nine academic sources, downloading PDFs, and performing AI-powered analysis of research papers. It also supports generating citation networks and recommending papers based on local workspace code.795MIT
- AlicenseNot gradedqualityDmaintenanceEnables searching, downloading, and exporting academic papers from 20+ scholarly sources including arXiv, PubMed, and Semantic Scholar. Supports multi-source concurrent search, citation network tracing, and export to CSV, RIS, and BibTeX.1MIT