Unpaywall MCP-Server

Ein MCP-Server (Model Context Protocol), der Unpaywall-Tools bereitstellt, damit KI-Clients:

• Metadaten per DOI abrufen

• Artikeltitel durchsuchen

• Die besten OA-Volltext-Links abrufen

• Text aus OA-PDFs herunterladen und extrahieren können

Schnellstart (npx)

Fügen Sie dies Ihrer MCP-Client-Konfiguration hinzu (Beispiel Claude Desktop):

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": { "UNPAYWALL_EMAIL": "you@example.com" }
    }
  }
}

Testen Sie dann die Tools: unpaywall_search_titles, unpaywall_get_fulltext_links, unpaywall_fetch_pdf_text.

Sie müssen dieses Repository nicht klonen oder npm install ausführen — npx kümmert sich beim ersten Aufruf um das Abrufen und Zwischenspeichern.

Related MCP server: ScholarScope MCP

Anforderungen

• Node.js 18+ (für npx)

• Eine E-Mail-Adresse für Unpaywall- / OpenAlex-Anfragen (von Unpaywall erforderlich, wird für den OpenAlex-Polite-Pool verwendet).

Lokale Entwicklung (nur für Mitwirkende)

Endbenutzer sollten die obige npx-Konfiguration verwenden. Mitwirkende, die aus dem Quellcode bauen:

npm install
npm run build
UNPAYWALL_EMAIL=you@example.com npm start   # stdio transport, as required by MCP clients

Hot-Run (ohne Build-Schritt):

UNPAYWALL_EMAIL=you@example.com npm run dev

Tools

unpaywall_get_by_doi

• Beschreibung: Ruft Unpaywall-Metadaten für eine DOI ab

• Eingabeschema:

  • doi (string, erforderlich): z. B. 10.1038/nphys1170

  • email (string, optional): überschreibt UNPAYWALL_EMAIL, falls angegeben

• Ausgabe: JSON-Antwort von Unpaywall

unpaywall_search_titles

• Beschreibung: Durchsucht Artikeltitel und gibt Unpaywall-artige OA-Metadaten für jeden Treffer zurück (50 Ergebnisse/Seite)

• Eingabeschema:

  • query (string, erforderlich): Titelsuche

  • is_oa (boolean, optional): wenn true, nur OA-Ergebnisse; wenn false, nur geschlossene; weglassen für alle

  • page (integer >= 1, optional): Seitennummer

  • email (string, optional): überschreibt UNPAYWALL_EMAIL

• Ausgabe: JSON, das dem Unpaywall-Suchformat entspricht — results[].response ist ein DOI-artiger Datensatz (doi, title, is_oa, oa_status, best_oa_location, oa_locations), mit score und snippet pro Ergebnis. _source: "openalex" markiert den Upstream.

• Hinweis: Unterstützt durch den /works-Endpunkt von OpenAlex, da Unpaywalls eigenes /v2/search seit der Überarbeitung im Mai 2025 HTTP 500 zurückgibt. Unpaywall fungiert jetzt als Unterroutine von OpenAlex, daher ist dies das kanonische moderne Äquivalent.

unpaywall_get_fulltext_links

• Beschreibung: Gibt die beste OA-PDF-URL und Open-URL für eine DOI sowie alle OA-Standorte zurück

• Eingabeschema:

  • doi (string, erforderlich)

  • email (string, optional): überschreibt UNPAYWALL_EMAIL

• Ausgabe: JSON mit den Feldern: best_pdf_url, best_open_url, best_oa_location, oa_locations und ausgewählten Metadaten

unpaywall_fetch_pdf_text

• Beschreibung: Lädt Text aus dem besten OA-PDF für eine DOI herunter und extrahiert ihn, oder von einer bereitgestellten pdf_url

• Eingabeschema:

  • pdf_url (string, optional): direkte PDF-URL (hat Vorrang)

  • doi (string, optional): wird verwendet, um das beste OA-PDF aufzulösen, falls keine pdf_url bereitgestellt wurde

  • email (string, optional): erforderlich, wenn doi verwendet wird und keine UNPAYWALL_EMAIL-Umgebungsvariable gesetzt ist

  • truncate_chars (integer >= 1000, optional): maximale Anzahl der zurückzugebenden Zeichen des extrahierten Textes (Standard 20000)

• Ausgabe: JSON mit text (möglicherweise gekürzt), length_chars, truncated, pdf_url und PDF-Metadaten

Tipps für LLM-Prompts (MCP)

Wenn Sie diesen Server von einem MCP-fähigen LLM-Client aus verwenden, bitten Sie das Modell:

• Suchen und dann abrufen: Verwenden Sie unpaywall_search_titles mit einem prägnanten Titel-Ausdruck; wählen Sie ein Ergebnis aus; rufen Sie dann unpaywall_get_fulltext_links oder unpaywall_fetch_pdf_text für die gewählte DOI auf.

• OA bevorzugen: Übergeben Sie is_oa: true bei Suchen, wenn Sie nur Open-Access-Ergebnisse wünschen.

• Größe kontrollieren: Setzen Sie truncate_chars in unpaywall_fetch_pdf_text (Standard 20000) und fassen Sie lange Texte zusammen, bevor Sie fortfahren.

• Resilient sein: Wenn die beste PDF-URL fehlt, greifen Sie auf best_open_url zurück und extrahieren Sie Inhalte von der Landingpage (außerhalb dieses Servers).

• Ratenbegrenzungen respektieren: Lassen Sie bei vielen Anfragen Zeit zwischen den Aufrufen; verwenden Sie frühere Antworten wieder, anstatt denselben Aufruf zu wiederholen.

Gute Benutzeranweisungen für das LLM:

• "Finde 3 OA-Arbeiten über 'foundation models in biomedicine', extrahiere dann die Einleitung der besten Arbeit und fasse sie zusammen."

• "Suche nach 'Graph Neural Networks survey 2024', filtere nach Möglichkeit auf OA, rufe dann den PDF-Text ab und erstelle eine Zusammenfassung mit 10 Stichpunkten."

Beispiel-Tool-Call-Payloads

Je nach MCP-Client unterscheidet sich die Struktur; die Kern-Payloads sind:

// Search titles
{
  "name": "unpaywall_search_titles",
  "arguments": {
    "query": "graph neural networks survey",
    "is_oa": true,
    "page": 1
  }
}

// Get best OA links for a DOI
{
  "name": "unpaywall_get_fulltext_links",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434"
  }
}

// Fetch and extract PDF text (by DOI)
{
  "name": "unpaywall_fetch_pdf_text",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434",
    "truncate_chars": 20000
  }
}

Konfiguration in einem MCP-Client

Empfohlene (No-Build) Konfiguration für Claude Desktop unter Verwendung von npm/npx:

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

Alternative (lokales Repo) Konfiguration unter Verwendung des kompilierten dist:

{
  "mcpServers": {
    "unpaywall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

Nach dem Hinzufügen bitten Sie Ihren Client, die Tools aufzulisten und zu testen:

• unpaywall_search_titles mit einer query

• unpaywall_get_fulltext_links mit einer doi

• unpaywall_fetch_pdf_text mit einer doi (oder pdf_url)

Hinweise

• Respektieren Sie die Ratenbegrenzungen und Nutzungsrichtlinien von Unpaywall: https://unpaywall.org/products/api

• Der Server verwendet stdio-Transport und @modelcontextprotocol/sdk.

• Setzen Sie UNPAYWALL_EMAIL oder übergeben Sie email pro Aufruf, damit Unpaywall Sie bezüglich der Nutzung kontaktieren kann.

Maintainer: Veröffentlichung auf npm

# 1) Build the project (also runs automatically on publish)
npm run build

# 2) Bump version (choose patch/minor/major)
npm version patch

# 3) Publish (ensure you are logged in: npm login)
npm publish --access public

# 4) Tag a release on GitHub (optional, recommended)

Benutzer können dann ihren MCP-Client mit npx -y unpaywall-mcp wie oben gezeigt konfigurieren. Kein Klonen oder Build erforderlich.