Paper Search MCP

A Model Context Protocol (MCP) server for searching and downloading academic papers from multiple sources. The project follows a free-first strategy: prioritize open and public data sources, support optional API keys when they improve stability or coverage, and keep source-specific connectors extensible for advanced users.

Table of Contents

• Overview

• Project Principles

• Features

• Source Strategy

• Sci-Hub Notice

• Installation

• Claude Code (Skill)

• Method 1 — Smithery

• Method 2 — uvx

• Method 3 — uv

• Method 4 — pip

• Method 5 — npx

• Method 6 — Docker

• Method 7 — Clone & run from source

• Environment Variables

• Contributing

• Demo

• Star History

• License

• TODO

Overview

paper-search-mcp is a Python-based tool for searching and downloading academic papers from various platforms. It provides tools for searching papers, downloading PDFs, and extracting text, making it ideal for researchers and AI-driven workflows. It can be used as an MCP server (for Claude Desktop and other MCP clients) or as a Claude Code skill with a CLI interface.

Project Principles

• Free-First: Public and open sources are the default roadmap. Paid or restricted sources are not the core direction of this project.

• Optional API Keys: API keys are supported only when they improve stability, rate limits, or metadata quality. The MCP should still be usable without them whenever possible.

• LLM-Friendly Retrieval: Search results should be standardized, deduplicated, and as complete as possible for downstream LLM workflows.

• Source Transparency: Different sources have different strengths. The MCP should make those tradeoffs explicit instead of pretending every source supports full-text retrieval.

Features

• Two-Layer Architecture:

• Layer 1 (Unified Tooling): High-level search_papers for multi-source concurrent search & deduplication, and download_with_fallback relying on publisher open access links with sequential fallbacks.

• Layer 2 (Platform Connectors): Modular connectors for specific academic platforms (arXiv, PubMed, bioRxiv, Semantic Scholar, etc.) equipped with intelligent DOI extraction via regex text analysis or API fields.

• Multi-Source Support: Search and download papers from arXiv, PubMed, bioRxiv, medRxiv, Google Scholar, IACR ePrint Archive, Semantic Scholar, Crossref, OpenAlex, PubMed Central (PMC), CORE, Europe PMC, dblp, OpenAIRE, CiteSeerX, DOAJ, BASE, Zenodo, HAL, SSRN, Unpaywall (DOI lookup), and optional Sci-Hub workflows.

• Standardized Output: Papers are returned in a consistent dictionary format via the Paper class.

• Free-First Design: Open and public sources are prioritized before any optional commercial or restricted integrations.

• Optional API-Key Enhancement: Sources like Semantic Scholar can work better with a user-provided API key, but are not intended to force paid usage.

• Discovery + Retrieval Workflow: Google Scholar and Crossref can be used for discovery and DOI backfilling, while open repositories and publisher links are used for lawful full-text resolution where available.

• OA-First Fallback Chain: download_with_fallback now follows source-native download → OpenAIRE/CORE/Europe PMC/PMC discovery → Unpaywall DOI resolution → optional Sci-Hub.

• MCP Integration: Compatible with MCP clients for LLM context enhancement.

• Extensible Design: Easily add new academic platforms by extending the academic_platforms module.

Source Strategy

The long-term goal is not to depend on a single search engine, but to combine multiple free and public sources with clear roles:

• Open metadata backbone: Crossref, OpenAlex, Semantic Scholar, dblp, CiteSeerX, SSRN, Unpaywall (DOI-centric OA metadata).

• Discipline-specific sources: arXiv, PubMed, PubMed Central, Europe PMC, IACR.

• Open-access full-text sources: arXiv, PMC, CORE, OpenAIRE, DOAJ, BASE, Zenodo, HAL, publisher open-access links.

• Discovery and DOI recovery: Google Scholar can be useful for finding titles, versions, and DOI clues when other public metadata sources are incomplete.

Recommended free-first roadmap:

• Keep current public sources stable.

• Add OpenAlex as a broad free metadata source.

• Add PubMed Central and Europe PMC for stronger biomedical full-text access.

• Add CORE and OpenAIRE for repository-based open-access retrieval.

• Use Google Scholar mainly as a discovery fallback, not as the primary canonical source.

Platform Capability Matrix

This matrix reflects verified live-integration results from functional and end-to-end regression tests in this repository. Columns show the highest capability level observed under normal conditions.

Platform Search Download Read Notes

arXiv ✅ ✅ ✅ Open API; reliable

PubMed ✅ ❌ ⚠️ info-only Open API; reliable

bioRxiv ✅ ✅ ✅ Open API; reliable

medRxiv ✅ ✅ ✅ Open API; reliable

Google Scholar ⚠️ ❌ ❌ Bot-detection active; set PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL

IACR ✅ ✅ ✅ Open API; reliable

Semantic Scholar ✅ ✅ (OA) ✅ (OA) Works without key (rate-limited); key improves limits; key rejection (403) retried automatically without key

Crossref ✅ ❌ ⚠️ info-only Open API; reliable

OpenAlex ✅ ❌ ⚠️ info-only Open API; reliable

PMC ✅ ✅ (OA only) ✅ (OA only) OA PDFs only; direct download may be blocked by some proxy environments

CORE ✅ ✅ (record-dependent) ✅ (record-dependent) Free key recommended; connector retries with backoff and falls back to key-less on 401/403

Europe PMC ✅ ✅ (OA) ✅ (OA) OA PDFs only; direct download may be blocked by some proxy environments

dblp ✅ ❌ ⚠️ info-only Open API; reliable

OpenAIRE ✅ ❌ ❌ Open API; retries 3× with escalating request profiles on transient 403

CiteSeerX ⚠️ ✅ (record-dependent) ⚠️ API endpoint intermittently unavailable / redirects to web archive

DOAJ ✅ ⚠️ (URL-dependent) ⚠️ (URL-dependent) PDF availability varies by article; free key raises rate limits

BASE ⚠️ ✅ (record-dependent) ✅ (record-dependent) OAI-PMH endpoint requires institutional IP registration; returns empty gracefully otherwise

Zenodo ✅ ✅ (record-dependent) ✅ (record-dependent) Open API; reliable

HAL ✅ ✅ (record-dependent) ✅ (record-dependent) Open API; reliable

SSRN ⚠️ ⚠️ best-effort ⚠️ best-effort 403 bot-detection active; public PDF only

Unpaywall ✅ (DOI lookup) ❌ ❌ Requires PAPER_SEARCH_MCP_UNPAYWALL_EMAIL

Sci-Hub (optional) ⚠️ fallback-only ✅ ❌ Optional; unstable mirrors; user responsibility

IEEE Xplore 🔑 🚧 skeleton 🚧 skeleton 🚧 skeleton Requires PAPER_SEARCH_MCP_IEEE_API_KEY to activate

ACM DL 🔑 🚧 skeleton 🚧 skeleton 🚧 skeleton Requires PAPER_SEARCH_MCP_ACM_API_KEY to activate

✅ = reliable in live tests. ⚠️ = works but subject to upstream instability or access restrictions. ❌ = not supported. 🔑 = key required. 🚧 = skeleton only.

Credential & API Key Requirements

All keys are optional unless noted. Configure them in ~/.config/paper-search-mcp/.env (preferred) or as shell exports.

Environment Variable Provider Required? How to obtain

PAPER_SEARCH_MCP_UNPAYWALL_EMAIL Unpaywall Yes (Unpaywall disabled without it) Any valid email; register at unpaywall.org

PAPER_SEARCH_MCP_CORE_API_KEY CORE Recommended Free at core.ac.uk/services/api

PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY Semantic Scholar Optional Free at semanticscholar.org — improves rate limits

PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL Google Scholar Optional Your HTTP/HTTPS proxy URL — bypasses bot-detection

PAPER_SEARCH_MCP_DOAJ_API_KEY DOAJ Optional Free at doaj.org — raises hourly rate limit

PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN Zenodo Optional Free at zenodo.org — required for private records

PAPER_SEARCH_MCP_IEEE_API_KEY IEEE Xplore Required to activate Free at developer.ieee.org

PAPER_SEARCH_MCP_ACM_API_KEY ACM DL Required to activate See libraries.acm.org/digital-library/acm-open

All variables follow the PAPER_SEARCH_MCP_<NAME> prefix scheme. Legacy names without the prefix (e.g. CORE_API_KEY, UNPAYWALL_EMAIL) are still supported for backward compatibility.

Known Upstream Limitations

Some search failures are caused by external provider instability, not by bugs in this project:

Source Symptom Cause Workaround

Google Sch