# unpaywall-mcp

[Polski](README.pl.md)

Unpaywall Open Access scholarly API MCP server. Looks up free-to-read versions
of papers by DOI and searches article titles for OA matches.

## Table of contents

- [Tools](#tools)
- [Environment variables](#environment-variables)
- [Wiring it up](#wiring-it-up)
- [Local run](#local-run)

## Tools

| Tool | Parameters | Description |
|------|------------|-------------|
| `get_doi` | `doi: str` | OA status + bibliographic metadata for a single DOI |
| `search_articles` | `query: str, is_oa: Optional[bool] = None, page: int = 1` | Search article titles; returns up to 50 DOI objects per page |

`search_articles` `query` modifiers: `"quoted phrase"` (contiguous), `OR`
(either term), `-term` (exclude). `is_oa` tri-state: `None` no filter, `True`
OA only, `False` non-OA only.

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `UNPAYWALL_MCP_EMAIL` | yes | Contact email Unpaywall requires on every request |

Unpaywall rate limit: 100,000 calls/day per email.

## Wiring it up

Only requirement: `uv` (https://docs.astral.sh/uv/). Nothing else to install.

### Claude Code

```
claude mcp add unpaywall-mcp -e UNPAYWALL_MCP_EMAIL=<your-email> -- uvx --from git+https://github.com/dam2452/unpaywall-mcp.git unpaywall-mcp
```

### Claude Desktop / other MCP client

```json
{
  "mcpServers": {
    "unpaywall-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dam2452/unpaywall-mcp.git", "unpaywall-mcp"],
      "env": { "UNPAYWALL_MCP_EMAIL": "<your-email>" }
    }
  }
}
```

After pushing a new version: `uv cache clean` and restart the client.

## Local run

```
uv run --directory . unpaywall-mcp
```

Tests (manual):

```
uv run --directory . --with pytest pytest test/
```