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
• MCP Authorization Compatibility
• 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
  • DeepSeek Harness (DSH)
  • 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.

---

MCP Authorization Compatibility

The bundled MCP server supports stdio (the default), sse, and streamable-http. Network transports bind to 127.0.0.1 by default. Optional OAuth protected-resource mode adds standard discovery, JWT bearer-token validation and required scopes to both HTTP transports, using an external authorization server.

Enable it with --auth oauth or PAPER_SEARCH_MCP_AUTH=oauth and the explicit issuer/JWKS/resource/audience/scope configuration in OAuth protected-resource setup. Invalid or incomplete HTTP auth settings fail startup. stdio remains independent of HTTP authentication. Local HTTP without OAuth configuration remains open; do not publish that listener directly. A protected remote deployment still needs TLS, rate limits and filesystem isolation. This feature does not host login/accounts or replace the external issuer's OAuth flow; live identity-provider interoperability must be validated for your deployment.

---

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, OpenReview, Unpaywall (DOI lookup), and optional Sci-Hub workflows.
• Opt-in Fast Search: CLI search keeps broad coverage by default. Use -s fast (OpenAlex, Crossref, arXiv, PubMed, Europe PMC) or -s fastest (OpenAlex and Crossref) when lower latency matters more than coverage.
• 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.
• Bounded reference lookups: OpenAlex references and citing papers from a DOI or OpenAlex ID, with explicit budgets and truncation metadata.
• MCP Integration: Compatible with MCP clients for LLM context enhancement.
• DeepSeek Harness (DSH) Integration: A dsh profile bundle (clone the repo, npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add link:./dsh) exposing every tool as mcp__paper-search__*, with an optional guidance skill.
• 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 engi