Unpaywall MCP Server

An MCP (Model Context Protocol) server exposing Unpaywall tools so AI clients can:

• Fetch metadata by DOI

• Search article titles

• Retrieve best OA fulltext links

• Download and extract text from OA PDFs

Quickstart (npx)

Add this to your MCP client config (Claude Desktop example):

Then try the tools: unpaywall_search_titles, unpaywall_get_fulltext_links, unpaywall_fetch_pdf_text.

Requirements

• Node.js 18+

• An email address for Unpaywall requests (they require it for polite usage).

Setup

For development with hot-run (no build step):

Tools

unpaywall_get_by_doi

• Description: Fetch Unpaywall metadata for a DOI

• Input schema:

  • doi (string, required): e.g. 10.1038/nphys1170

  • email (string, optional): overrides UNPAYWALL_EMAIL if provided

• Output: JSON response from Unpaywall

unpaywall_search_titles

• Description: Search Unpaywall for article titles matching a query (50 results/page)

• Input schema:

  • query (string, required): title query

  • is_oa (boolean, optional): if true, only OA results; if false, only closed; omit for all

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

  • email (string, optional): overrides UNPAYWALL_EMAIL

• Output: JSON search results from GET https://api.unpaywall.org/v2/search

unpaywall_get_fulltext_links

• Description: Return the best OA PDF URL and Open URL for a DOI, plus all OA locations

• Input schema:

  • doi (string, required)

  • email (string, optional): overrides UNPAYWALL_EMAIL

• Output: JSON with fields: best_pdf_url, best_open_url, best_oa_location, oa_locations, and select metadata

unpaywall_fetch_pdf_text

• Description: Download and extract text from the best OA PDF for a DOI, or from a provided pdf_url

• Input schema:

  • pdf_url (string, optional): direct PDF URL (takes precedence)

  • doi (string, optional): used to resolve best OA PDF if pdf_url not provided

  • email (string, optional): required if using doi and no UNPAYWALL_EMAIL env var

  • truncate_chars (integer >= 1000, optional): max characters of extracted text to return (default 20000)

• Output: JSON with text (possibly truncated), length_chars, truncated, pdf_url, and PDF metadata

LLM prompting tips (MCP)

When using this server from an MCP-enabled LLM client, ask the model to:

• Search then fetch: Use unpaywall_search_titles with a concise title phrase; select a result; then call unpaywall_get_fulltext_links or unpaywall_fetch_pdf_text on the chosen DOI.

• Prefer OA: Pass is_oa: true in searches when you only want open-access.

• Control size: Set truncate_chars in unpaywall_fetch_pdf_text (default 20000) and summarize long texts before proceeding.

• Be resilient: If the best PDF URL is missing, fall back to best_open_url and extract content from the landing page (outside this server).

• Respect rate limits: Space requests if making many calls; reuse earlier responses instead of repeating the same call.

Good user instructions to the LLM:

• "Find 3 OA papers about 'foundation models in biomedicine', then extract and summarize the introduction of the best one."

• "Search for 'Graph Neural Networks survey 2024', filter to OA if possible, then fetch the PDF text and produce a 10-bullet summary."

Example tool call payloads

Depending on your MCP client, the structure differs; the core payloads are:

Configure in an MCP client

Recommended (no-build) config for Claude Desktop using npm/npx:

Alternative (local repo) config using the compiled dist:

After adding, ask your client to list tools and try:

• unpaywall_search_titles with a query

• unpaywall_get_fulltext_links with a doi

• unpaywall_fetch_pdf_text with a doi (or pdf_url)

Notes

• Respect Unpaywall's rate limits and usage guidelines: https://unpaywall.org/products/api

• The server uses stdio transport and @modelcontextprotocol/sdk.

• Set UNPAYWALL_EMAIL or pass email per call so Unpaywall can contact you about usage.

Maintainers: publish to npm

Users can then configure their MCP client with npx -y unpaywall-mcp as shown above. No clone or build required.