Paper Search MCP

Ein Model Context Protocol (MCP)-Server zum Suchen und Herunterladen von akademischen Papieren aus mehreren Quellen. Das Projekt folgt einer Free-First-Strategie: offene und öffentliche Datenquellen werden priorisiert, optionale API-Schlüssel werden unterstützt, wenn sie die Stabilität oder Abdeckung verbessern, und quellenspezifische Konnektoren bleiben für fortgeschrittene Benutzer erweiterbar.

Inhaltsverzeichnis

• Überblick

• Projektprinzipien

• Funktionen

• Quellenstrategie

• Sci-Hub-Hinweis

• Installation

  • Claude Code (Skill)

  • Methode 1 — Smithery

  • Methode 2 — uvx

  • Methode 3 — uv

  • Methode 4 — pip

  • Methode 5 — npx

  • Methode 6 — Docker

  • Methode 7 — Klonen und aus dem Quellcode ausführen

  • Umgebungsvariablen

• Mitwirken

• Demo

• Sterne-Verlauf

• Lizenz

• TODO

Related MCP server: Academic Paper MCP HTTP/SSE Server

Überblick

paper-search-mcp ist ein Python-basiertes Werkzeug zum Suchen und Herunterladen von akademischen Papieren von verschiedenen Plattformen. Es bietet Werkzeuge zum Suchen von Papieren, Herunterladen von PDFs und Extrahieren von Text und ist damit ideal für Forscher und KI-gesteuerte Arbeitsabläufe. Es kann als MCP-Server (für Claude Desktop und andere MCP-Clients) oder als Claude-Code-Skill mit einer CLI-Schnittstelle verwendet werden.

Projektprinzipien

• Free-First: Öffentliche und offene Quellen sind die Standard-Roadmap. Bezahlte oder eingeschränkte Quellen sind nicht der Kern dieses Projekts.

• Optionale API-Schlüssel: API-Schlüssel werden nur unterstützt, wenn sie die Stabilität, Ratenlimits oder Metadatenqualität verbessern. Der MCP sollte ohne sie möglichst weiterhin nutzbar sein.

• LLM-freundlicher Abruf: Suchergebnisse sollten standardisiert, dedupliziert und für nachgelagerte LLM-Workflows so vollständig wie möglich sein.

• Quellentransparenz: Verschiedene Quellen haben unterschiedliche Stärken. Der MCP sollte diese Kompromisse explizit machen, anstatt so zu tun, als ob jede Quelle Volltextabruf unterstützt.

Funktionen

• Zweischichtige Architektur:

  • Schicht 1 (Einheitliche Werkzeuge): Hochrangiges search_papers für mehrquellen-konkurrente Suche und Deduplizierung sowie download_with_fallback, das sich auf Open-Access-Links der Verlage mit sequenziellen Fallbacks stützt.

  • Schicht 2 (Plattform-Konnektoren): Modulare Konnektoren für spezifische akademische Plattformen (arXiv, PubMed, bioRxiv, Semantic Scholar usw.) mit intelligenter DOI-Extraktion über Regex-Textanalyse oder API-Felder.

• Mehrquellen-Unterstützung: Suche und Download von Papieren von 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-Suche) und optionalen Sci-Hub-Workflows.

• Standardisierte Ausgabe: Papiere werden in einem konsistenten Wörterbuchformat über die Paper-Klasse zurückgegeben.

• Free-First-Design: Offene und öffentliche Quellen werden vor optionalen kommerziellen oder eingeschränkten Integrationen priorisiert.

• Optionale API-Schlüssel-Verbesserung: Quellen wie Semantic Scholar können mit einem vom Benutzer bereitgestellten API-Schlüssel besser funktionieren, sind aber nicht dazu gedacht, bezahlte Nutzung zu erzwingen.

• Discovery- und Abruf-Workflow: Google Scholar und Crossref können für Discovery und DOI-Nachfüllung verwendet werden, während offene Repositorien und Verlagslinks für die rechtmäßige Volltextauflösung verwendet werden, wo verfügbar.

• OA-First-Fallback-Kette: download_with_fallback folgt jetzt Quell-eigenem Download → OpenAIRE/CORE/Europe PMC/PMC-Discovery → Unpaywall-DOI-Auflösung → optionalem Sci-Hub.

• MCP-Integration: Kompatibel mit MCP-Clients zur LLM-Kontextverbesserung.

• Erweiterbares Design: Einfaches Hinzufügen neuer akademischer Plattformen durch Erweiterung des academic_platforms-Moduls.

Quellenstrategie

Das langfristige Ziel ist nicht, sich auf eine einzelne Suchmaschine zu verlassen, sondern mehrere freie und öffentliche Quellen mit klaren Rollen zu kombinieren:

• Offene Metadaten-Backbone: Crossref, OpenAlex, Semantic Scholar, dblp, CiteSeerX, SSRN, Unpaywall (DOI-zentrierte OA-Metadaten).

• Fachspezifische Quellen: arXiv, PubMed, PubMed Central, Europe PMC, IACR.

• Open-Access-Volltextquellen: arXiv, PMC, CORE, OpenAIRE, DOAJ, BASE, Zenodo, HAL, Open-Access-Links von Verlagen.

• Discovery und DOI-Wiederherstellung: Google Scholar kann nützlich sein, um Titel, Versionen und DOI-Hinweise zu finden, wenn andere öffentliche Metadatenquellen unvollständig sind.

Empfohlene Free-First-Roadmap:

1. Aktuelle öffentliche Quellen stabil halten.

2. OpenAlex als breite freie Metadatenquelle hinzufügen.

3. PubMed Central und Europe PMC für stärkeren biomedizinischen Volltextzugriff hinzufügen.

4. CORE und OpenAIRE für repositorienbasierten Open-Access-Abruf hinzufügen.

5. Google Scholar hauptsächlich als Discovery-Fallback verwenden, nicht als primäre kanonische Quelle.

Plattform-Fähigkeitsmatrix

Diese Matrix spiegelt verifizierte Live-Integrationsergebnisse aus funktionalen und End-to-End-Regressionstests in diesem Repository wider. Die Spalten zeigen die höchste beobachtete Fähigkeitsstufe unter normalen Bedingungen.

✅ = zuverlässig in Live-Tests. ⚠️ = funktioniert, aber anfällig für Upstream-Instabilität oder Zugriffsbeschränkungen. ❌ = nicht unterstützt. 🔑 = Schlüssel erforderlich. 🚧 = nur Gerüst.

Anforderungen an Anmeldeinformationen und API-Schlüssel

Alle Schlüssel sind optional, sofern nicht anders angegeben. Konfigurieren Sie sie in ~/.config/paper-search-mcp/.env (bevorzugt) oder als Shell-Exporte.

Alle Variablen folgen dem Präfix-Schema PAPER_SEARCH_MCP_<NAME>. Legacy-Namen ohne das Präfix (z. B. CORE_API_KEY, UNPAYWALL_EMAIL) werden aus Gründen der Abwärtskompatibilität weiterhin unterstützt.

Bekannte Einschränkungen der Upstream-Dienste

Einige Suchfehler werden durch externe Anbieter-Instabilität verursacht, nicht durch Fehler in diesem Projekt:

Optionale kostenpflichtige Plattform-Connectors (Phase 3)

Die Connectors für IEEE Xplore und ACM Digital Library sind als Opt-in-Gerüste enthalten. Sie sind standardmäßig deaktiviert — es werden keine API-Aufrufe getätigt, es sei denn, Sie konfigurieren die entsprechenden Schlüssel explizit.

So aktivieren Sie sie:

export PAPER_SEARCH_MCP_IEEE_API_KEY=<your_ieee_key>       # free key at https://developer.ieee.org/
export PAPER_SEARCH_MCP_ACM_API_KEY=<your_acm_key>         # see https://libraries.acm.org/digital-library

Sobald ein Schlüssel gesetzt ist, wird die entsprechende Quelle automatisch zu ALL_SOURCES hinzugefügt und ihre MCP-Tools (search_ieee / search_acm, download_ieee / download_acm, read_ieee_paper / read_acm_paper) werden beim Serverstart registriert.

Ohne einen Schlüssel protokollieren die Connectors nur eine Startwarnung — der Rest des Servers bleibt unberührt.

Erweiterung um kostenlose Quellen (Phase 4)

Drei weitere kostenlose Quellen-Connectors sind jetzt in den MCP-Server integriert:

• zenodo: Offizieller Zenodo-REST-API-Connector (Suche + datensatzabhängige PDF-/Leseunterstützung).

• hal: HAL-öffentlicher-API-Connector (Suche + datensatzabhängige PDF-/Leseunterstützung).

• ssrn: Discovery-orientierter Connector mit robustem Parser und Best-Effort-Download/Lesen, wenn ein direkter öffentlicher PDF-Link verfügbar ist.

• unpaywall: DOI-zentrierte OA-Metadatenquelle für eigenständige Suche (search_unpaywall) und Fallback-URL-Auflösung.

Die SSRN-Integration bleibt compliance-orientiert: Sie versucht nur direkte öffentliche PDF-Links, die von SSRN-Seiten bereitgestellt werden. Wenn Login oder eingeschränkte Zustellung erforderlich ist, gibt der Connector eine klare Meldung zurück, anstatt Zugriffskontrollen zu umgehen.

Sci-Hub-Hinweis

Die Sci-Hub-Unterstützung kann als optionaler Connector für Benutzer verfügbar bleiben, die sie explizit aktivieren möchten, sollte aber nicht als Standard- oder empfohlener Volltextpfad behandelt werden.

• Die Verfügbarkeit ist instabil und Spiegel ändern sich häufig.

• Rechtliche und politische Risiken variieren je nach Rechtsraum.

• README und Tool-Beschreibungen sollten klar angeben, dass die Benutzer für die Aktivierung und Nutzung verantwortlich sind.

• Open-Access- und verlagserlaubte Quellen sollten wann immer möglich zuerst versucht werden.

Installation

Wählen Sie die Methode, die am besten zu Ihrem Arbeitsablauf passt. Alle Methoden unterstützen dieselben optionalen API-Schlüssel.

Claude Code (Skill) — empfohlen für Claude-Code-Benutzer

Installieren Sie es als Claude-Code-Skill anstelle eines MCP-Servers. Das gibt Claude automatischen Zugriff auf die Papiersuche, wenn Sie das Finden von Papieren, akademischer Literatur usw. erwähnen — keine MCP-Konfiguration erforderlich.

Voraussetzungen: uv und Claude Code.

Schritt 1 — CLI installieren:

uv tool install paper-search-mcp

Schritt 2 — Skill installieren:

mkdir -p ~/.claude/skills/paper-search
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/claude-code/SKILL.md \
  -o ~/.claude/skills/paper-search/SKILL.md

Schritt 3 (optional) — API-Schlüssel konfigurieren:

Erstellen Sie ~/.config/paper-search-mcp/.env für optionale API-Schlüssel (siehe Umgebungsvariablen).

Das war's. Wenn Sie das nächste Mal Claude Code starten, bitten Sie es einfach, Papiere zu finden — der Skill aktiviert sich automatisch. Zum Beispiel:

• „Finde mir aktuelle Papiere über CRISPR-Basen-Editing"

• „Suche auf arxiv und semantic scholar nach Transformer-Aufmerksamkeitsmechanismen"

• „Lade das PDF für arxiv-Papier 2106.12345 herunter"

Der Skill verwendet eine CLI (paper-search), die dieselbe Bibliothek wie der MCP-Server umschließt und JSON für Suche/Download und Klartext für Lesen ausgibt.

MCP-Server-Konfigurationsdatei-Speicherorte (für die folgenden Methoden)

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Methode 1 — Smithery (Ein-Befehl, empfohlen für Claude Desktop)

npx -y @smithery/cli install @openags/paper-search-mcp --client claude

Smithery schreibt automatisch den korrekten Konfigurationsblock für Sie. Kein manuelles JSON-Bearbeiten erforderlich.

Methode 2 — uvx (keine Installation, immer aktuell)

uvx führt das Paket direkt von PyPI aus, ohne dauerhafte Installation. Erfordert uv.

# Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

⚠️ macOS-Hinweis: Von uvx generierte Wrapper-Skripte verlassen sich auf realpath, das in macOS standardmäßig nicht enthalten ist. Wenn Sie einen Fehler realpath: command not found sehen, installieren Sie entweder GNU coreutils (brew install coreutils) oder verwenden Sie stattdessen Methode 3 (uv run) — diese hat diese Einschränkung nicht.

Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uvx",
      "args": ["paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Methode 3 — uv (dauerhafte Installation)

uv tool install paper-search-mcp

Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": ["tool", "run", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Methode 4 — pip (Standard-Python-Installation)

pip install paper-search-mcp

Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "python",
      "args": ["-m", "paper_search_mcp.server"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Wenn python nicht in Ihrem PATH ist, ersetzen Sie es durch den vollständigen Pfad (z. B. /usr/bin/python3 oder C:\Python311\python.exe). Führen Sie which python3 / where python aus, um es zu finden.

Methode 5 — npx (über Smithery CLI, kein lokales Python erforderlich)

npx -y @smithery/cli run @openags/paper-search-mcp

Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@openags/paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": ""
      }
    }
  }
}

Methode 6 — Docker

docker build -t paper-search-mcp .
docker run --rm -i \
  -e PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com \
  -e PAPER_SEARCH_MCP_CORE_API_KEY=your_core_key \
  paper-search-mcp

Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Methode 7 — Klonen und aus dem Quellcode ausführen (Entwicklung / empfohlen für lokales macOS)

Dies ist die zuverlässigste Methode auf macOS — keine Wrapper-Skripte, keine realpath-Probleme.

# 1. Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone repo
git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp

# 3. Verify it runs (uv auto-resolves dependencies, no manual install needed)
uv run -m paper_search_mcp.server

Claude-Desktop-Konfiguration (ersetzen Sie den Verzeichnispfad durch Ihren tatsächlichen Klonort):

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/paper-search-mcp",
        "-m", "paper_search_mcp.server"
      ],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

Wenn Sie zum Beispiel nach /Users/mac/Pengsong/paper-search-mcp geklont haben:

"args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.server"]

uv run installiert beim ersten Ausführen automatisch Abhängigkeiten in eine isolierte Umgebung — kein pip install oder venv erforderlich.

Für aktive Entwicklung können Sie optional eine bearbeitbare Kopie installieren:

uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

Umgebungsvariablen (.env-Datei)

Anstatt Schlüssel direkt in die JSON-Konfiguration zu setzen, können Sie sie in der Benutzerkonfigurationsdatei speichern (wird beim Start automatisch geladen):

mkdir -p ~/.config/paper-search-mcp
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/.env.example \
  -o ~/.config/paper-search-mcp/.env
$EDITOR ~/.config/paper-search-mcp/.env

PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com
PAPER_SEARCH_MCP_CORE_API_KEY=
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=
PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN=
PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL=
PAPER_SEARCH_MCP_IEEE_API_KEY=
PAPER_SEARCH_MCP_ACM_API_KEY=

Um einen benutzerdefinierten Pfad zu verwenden: export PAPER_SEARCH_MCP_ENV_FILE=/absoluter/pfad/zu/.env

Legacy-Variablennamen ohne das PAPER_SEARCH_MCP_-Präfix (z. B. CORE_API_KEY, UNPAYWALL_EMAIL) werden aus Gründen der Abwärtskompatibilität weiterhin unterstützt.

Mitwirken

Wir freuen uns über Beiträge! So legen Sie los:

1. Repository forken: Klicken Sie auf „Fork" auf GitHub.

2. Klonen und einrichten:

   git clone https://github.com/yourusername/paper-search-mcp.git
   cd paper-search-mcp
   uv venv && source .venv/bin/activate
   uv pip install -e ".[dev]"

3. Änderungen vornehmen:

   • Fügen Sie neue Plattformen in academic_platforms/ hinzu.

   • Aktualisieren Sie Tests in tests/.

4. Pull-Request einreichen: Pushen Sie Änderungen und erstellen Sie einen PR auf GitHub.

Demo

TODO

Geplante akademische Plattformen

• [√] arXiv

• [√] PubMed

• [√] bioRxiv

• [√] medRxiv

• [√] Google Scholar

• [√] IACR ePrint Archive

• [√] Semantic Scholar

• [√] Crossref

• [√] PubMed Central (PMC)

• [√] CORE

• [√] Europe PMC

• [√] Sci-Hub-Warnung und Aktivierungsdokumentation

Entwicklungsaufgaben

• [√] Behebe Async-Suchfehler und stelle zuverlässige schnelle MCP-Ereignisse sicher

• [√] End-to-End-Testskript für die vollständige Pipeline (Suche, Parsen, Herunterladen)

• [√] Etabliere eine zweischichtige föderierte Architektur (Layer-1-Tool: search_papers)

• [√] Stelle eine durchgängige DOI-Extraktion über Metadatenfelder und Abstract-Fallbacks sicher

• Zitationsgraph- und Papierbeziehungskontext-Funktion

• [√] Erweitere den Full-Stack-OpenAlex-Anbieter

Prioritäre freie und offene Quellen

• [√] PubMed Central (PMC)

• [√] CORE

• [√] OpenAlex

• [√] Europe PMC

• [√] OpenAIRE

• [√] dblp

• [√] CiteSeerX

• [√] DOAJ

• [√] BASE

• [√] Zenodo

• [√] HAL

• [√] SSRN (Discovery + Best-Effort-Volltext)

• [√] Unpaywall (eigenständige DOI-Suchquelle)

Optionale und nicht-kernige Integrationen

• ResearchGate

• JSTOR

• ScienceDirect

• Springer Link

• [√] IEEE Xplore (optionales Grundgerüst — mit IEEE_API_KEY aktivieren)

• [√] ACM Digital Library (optionales Grundgerüst — mit ACM_API_KEY aktivieren)

• Web of Science

• Scopus

Star History

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Details finden Sie in der LICENSE-Datei.

Viel Erfolg bei der Recherche mit paper-search-mcp! Wenn Sie auf Probleme stoßen, öffnen Sie ein GitHub-Issue.