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):

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

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

# Install deps
npm install

# Build
npm run build

# Run (stdio transport, as required by MCP clients)
UNPAYWALL_EMAIL=you@example.com npm start

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

UNPAYWALL_EMAIL=you@example.com npm run dev

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:

// 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
  }
}

Configure in an MCP client

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

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

Alternative (local repo) config using the compiled dist:

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

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

# 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)

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