# Unpaywall Mcp

> AnModel Context Protocol (MCP) server for the Unpaywall API. Search article titles, fetch DOI metadata, retrieve best open‑access links, and extract text from OA PDFs—ready for Claude Desktop and any MCP‑compatible client. Ideal for LLM research assistants, literature review, and academic workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-elliotpadfield-unpaywall-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ElliotPadfield](https://agentstack.voostack.com/s/elliotpadfield)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ElliotPadfield](https://github.com/ElliotPadfield)
- **Source:** https://github.com/ElliotPadfield/unpaywall-mcp

## Install

```sh
agentstack add mcp-elliotpadfield-unpaywall-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Unpaywall MCP Server
[](https://www.npmjs.com/package/unpaywall-mcp)
[](https://github.com/ElliotPadfield/unpaywall-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](#requirements)

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

```jsonc
{
  "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`.

You don't need to clone this repo or run `npm install` — `npx` handles fetching and caching on first call.

## Requirements

- Node.js 18+ (for `npx`)
- An email address for Unpaywall / OpenAlex requests (required by Unpaywall, used for the OpenAlex polite pool).

## Local development (contributors only)

End users should use the npx config above. Contributors building from source:

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

Hot-run (no build step):

```bash
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 article titles and return Unpaywall-style OA metadata for each hit (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 matching the Unpaywall search shape — `results[].response` is a DOI-style record (`doi`, `title`, `is_oa`, `oa_status`, `best_oa_location`, `oa_locations`), with `score` and `snippet` per result. `_source: "openalex"` marks the upstream.
- Note: Backed by OpenAlex's `/works` endpoint because Unpaywall's own `/v2/search` has been returning HTTP 500 since its May 2025 rewrite. Unpaywall now runs as a subroutine of OpenAlex, so this is the canonical modern equivalent.

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

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

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

```jsonc
// 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:

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

Alternative (local repo) config using the compiled dist:

```jsonc
{
  "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

```bash
# 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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ElliotPadfield](https://github.com/ElliotPadfield)
- **Source:** [ElliotPadfield/unpaywall-mcp](https://github.com/ElliotPadfield/unpaywall-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-elliotpadfield-unpaywall-mcp
- Seller: https://agentstack.voostack.com/s/elliotpadfield
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.