unpaywall

The Unpaywall MCP Server exposes Unpaywall data retrieval tools via the MCP protocol. It provides a set of tools you can invoke from an MCP client to fetch metadata by DOI, search article titles, obtain best OA fulltext links, and fetch or extract text from OA PDFs. Typical workflows involve first searching for papers by a title phrase, selecting a DOI from the results, and then requesting either the best OA PDF link or the extracted text from that PDF. You can also pass an email per call or rely on the UNPAYWALL_EMAIL environment variable for polite usage.

Common tool workflow: use unpaywall_search_titles to find OA-friendly results, then call unpaywall_get_fulltext_links on the chosen DOI to retrieve the best PDF URL and related OA locations. If you have a direct PDF URL or need the full text, use unpaywall_fetch_pdf_text with either a pdf_url or a doi. The server supports overriding the default email per call via the email field in each tool’s input. All outputs are JSON payloads from the Unpaywall API or the server’s processing layer, suitable for downstream LLM prompting or further MCP processing.

Prerequisites:

• Node.js 18+ installed on the host
• npm (comes with Node.js) or corepack available

Install and run locally using npm:

# 1) Install dependencies and build (if needed by the project)
npm install

# 2) Build the project (optional if the MCP server supports runtime on-the-fly) 
npm run build

# 3) Start the MCP server (stdio transport required by MCP clients)
UNPAYWALL_EMAIL=you@example.com npm start

Development workflow (hot-reload, no build):

UNPAYWALL_EMAIL=you@example.com npm run dev

If you prefer to run via npx without local install, the MCP server can be started through npx as shown in the Quickstart:

UNPAYWALL_EMAIL=you@example.com npx unpaywall-mcp

Notes:

• Ensure the UNPAYWALL_EMAIL is set to a valid address for Unpaywall API usage.
• The npm package name is unpaywall-mcp.

Tips and caveats:

• Respect Unpaywall rate limits and usage guidelines. Space out requests when performing multiple lookups.
• The MCP server uses stdio transport; ensure your client is configured accordingly.
• If you encounter missing best PDF URLs, you can fall back to the best_open_url or the landing page content as a fallback per the prompts guidance.
• You can override the default email per call by providing email in the tool input; otherwise UNPAYWALL_EMAIL from env is used.
• For best results, prefer OA results in searches by setting is_oa: true when listing candidate papers.