Content
# 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/
```
