Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@unpaywall-mcp Look up DOI 10.1038/s41586-023-00000-0"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unpaywall Open Access scholarly API MCP server. Looks up free-to-read versions of papers by DOI and searches article titles for OA matches.
Related MCP server: OpenAlex MCP Server
Tool | Parameters | Description |
|
| OA status + bibliographic metadata for a single DOI |
|
| 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.
Variable | Required | Description |
| yes | Contact email Unpaywall requires on every request |
Unpaywall rate limit: 100,000 calls/day per email.
Only requirement: uv (https://docs.astral.sh/uv/). Nothing else to install.
claude mcp add unpaywall-mcp -e UNPAYWALL_MCP_EMAIL=<your-email> -- uvx --from git+https://github.com/dam2452/unpaywall-mcp.git unpaywall-mcp{
"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.
uv run --directory . unpaywall-mcpTests (manual):
uv run --directory . --with pytest pytest test/Look up Open Access status and bibliographic metadata for a single DOI.
Returns the full Unpaywall DOI object: title, authors, publication info, OA status, best OA location (free PDF link if available), and more.
Examples: get_doi(doi="10.1038/nature12373") get_doi(doi="10.1007/s11222-022-10107-2")
| Name | Required | Description | Default |
|---|---|---|---|
| doi | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description details the return object (full Unpaywall DOI object) but does not mention rate limits, authentication, or error handling. It assumes a read-only operation but does not confirm.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with examples; no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with an output schema, adequately covers the tool's behavior for a simple single-DOI lookup. Lacks details on error scenarios but sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter 'doi' and 0% schema description coverage, the description provides examples but does not specify required format, validation, or constraints beyond being a string.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up Open Access status and bibliographic metadata for a single DOI, and distinguishes from the sibling tool 'search_articles' which is for searching multiple articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates use for a single DOI with examples, but does not explicitly state when not to use or alternative scenarios. The sibling tool name 'search_articles' provides implicit contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Unpaywall article titles and return matching DOI objects.
Search terms are whitespace-split and AND-ed by default. Modifiers inside
query:
"quoted phrase" : words must appear as a contiguous phrase
OR : match either term (replaces default AND)
-term : exclude titles containing this term
Returns up to 50 results per page, sorted by match score. Each result
contains the full DOI object, a numeric score, and an HTML snippet
showing where the query matched the title.
Examples: search_articles(query="cell thermometry") search_articles(query='single "cell thermometry"', is_oa=True) search_articles(query="machine learning OR deep learning", is_oa=False, page=2)
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| is_oa | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains search behavior (whitespace-split, AND by default, modifiers), pagination, sorting, and result structure (DOI object, score, snippet). It does not mention rate limits or auth, but covers core behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose, syntax, pagination/results, examples. No unnecessary sentences. Examples are concise and illustrative. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no annotations, and output schema existing, the description covers search syntax, pagination, result fields, and examples. It could mention the default value for is_oa or page limit, but overall is informative enough for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains query syntax in detail (modifiers), shows is_oa filter in examples, and mentions page parameter. It does not explicitly define is_oa's default or allowed values, but examples clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search Unpaywall article titles and return matching DOI objects,' clearly specifying the verb, resource, and return type. It distinguishes from sibling get_doi by focusing on search rather than single DOI retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description details search syntax (AND, quoted phrases, OR, exclusion), pagination (up to 50 per page), and sorting by score. Examples demonstrate usage with modifiers and filters. However, it does not explicitly state when to prefer this tool over get_doi, but the purpose implies differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_doisearch_articlesScored across 2 tools
The two tools have clearly distinct purposes: get_doi retrieves data for a known DOI, while search_articles finds articles by title query. No overlap or ambiguity.
Both tools follow a consistent verb_noun pattern: get_doi and search_articles. The naming is predictable and easy to understand.
Two tools is lean but reasonable for a focused API that covers the primary use cases: fetching by DOI and searching by title. Could be expanded with additional identifiers, but the count is appropriate for a minimal server.
The server covers the core functionality of the Unpaywall API: single DOI lookup and title search. Minor gaps exist (e.g., no batch operations or search by other metadata), but the main workflows are supported.
Unpaywall MCP — open-access lookup for scholarly papers (free, no key)
Academic literature search, retrieval, and private library management on top of OpenAlex.
Search 150M+ academic works, journals, and funders via Crossref API.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
