paperfind-mcp (Paperfind)

Paperfind is a read-only Model Context Protocol connector for academic paper metadata and links. It searches arXiv, Crossref, OpenAlex, Europe PMC, PubMed, and DOAJ, and it asks Unpaywall for open-access locations by DOI. Every tool is read-only. The server speaks stdio, and it can serve stateless Streamable HTTP on 127.0.0.1 only.

A paper record carries normalized ids (DOI in lowercase without a https://doi.org/ prefix, plus arXiv, PMID, PMCID, OpenAlex, and DOAJ ids when a source provides them), title, authors, year, venue, abstract, landing and PDF links, open-access fields, citation count, and the sources that returned the record. Search merges duplicates that share a DOI, or that share a normalized title and year when their strong ids do not conflict. The richest abstract wins. An abstract without a copyright note beats a longer abstract that carries one. Source lists and ids are unioned.

Connects to: public scholarly APIs (arXiv, Crossref, OpenAlex, Europe PMC, PubMed / NCBI E-utilities, DOAJ, and Unpaywall). Keys for OpenAlex and NCBI are optional.

The npm package, binary, and User-Agent name are papers.

By Issah Abubakari (@si-essence). Also listed on Bot Essentials.

Requirements

• Node.js 20 or newer (CI uses Node.js 22)

• npm

Related MCP server: Papers by Ouroboros Apps

Tools

Limits default to 5 and max out at 25. Page defaults to 1 and maxes out at 200. yearFrom must be less than or equal to yearTo.

Tool errors use these prefixes and name the source: [invalid-input], [not-found], [rate-limited], [upstream], [timeout], [config]. Messages do not include stack traces or secret values.

Setup

From a clone of this repository:

npm ci
npm run ci          # typecheck, lint, test, build
npm start           # stdio
npm run start:http  # http://127.0.0.1:3000/mcp and /health
node scripts/live-check.mjs   # optional, calls the real public APIs

Copy .env.example and export the variables, or set them in the client config.

{
  "mcpServers": {
    "papers": {
      "command": "node",
      "args": ["/path/to/paperfind-mcp/dist/index.js"],
      "env": {
        "PAPERS_CONTACT_EMAIL": "contact@example.com"
      }
    }
  }
}

OPENALEX_API_KEY and NCBI_API_KEY are optional. Leave them unset for keyless limits. Do not log them.

Docker binds HTTP with no authentication. Keep the port on localhost.

docker build -t papers .
docker run -p 3000:3000 -e PAPERS_CONTACT_EMAIL=contact@example.com papers

The image sets PAPERS_CONTACT_EMAIL=contact@example.com. Override it with an address you control. Do not bake a personal address or an API key into the image.

Environment

Invalid values are reported by field name and issue code. The rejected value is not included in the error.

The User-Agent is papers/0.1.0 (mailto:<PAPERS_CONTACT_EMAIL>).

Sources and terms

Checked on 2026-10-17. The rate column is what this process enforces.

An open licence here means a Creative Commons licence (the string starts with cc or names creativecommons.org), CC0, or public domain. The full-text cap is 80,000 characters. The licence string is returned with any text.

Excluded sources

Semantic Scholar is excluded. Its API licence forbids repackaging, selling, renting, leasing, lending, distributing, or sublicensing the API, some of the data is CC BY-NC, and Ai2 ships an official MCP. Google Scholar is excluded because it has no API for this use and scraping breaks its terms. Sci-Hub and LibGen are excluded because they distribute texts without a licence to do so.

Attribution

Metadata comes from Crossref. OpenAlex data is CC0. arXiv metadata is CC0. Thank you to arXiv for use of its open access interoperability. Europe PMC records are used through its REST API. This connector uses NCBI E-utilities from the National Library of Medicine (NLM). NLM is not responsible for this project and does not endorse it. DOAJ article metadata is CC0. Unpaywall locations come from the Unpaywall API, now documented by OpenAlex. None of these providers endorse this project.

Limits and caveats

• Crossref does not publish a fixed numeric polite-pool rate. This connector starts at 334 ms between Crossref calls, only lengthens that gap when X-Rate-Limit-Limit and X-Rate-Limit-Interval ask for a slower pace, and honours Retry-After on HTTP 429.

• contact@example.com is a placeholder. Unpaywall rejects it with HTTP 422 and asks for the caller's own email. In that case find_open_access reports Unpaywall as unavailable and still returns the OpenAlex location. Set PAPERS_CONTACT_EMAIL to an address you control. When both lookups fail, the tool returns a reason and per-source statuses. Upstream error text replaces http and https URLs with [url].

• Unpaywall is used for the DOI lookup GET /v2/{doi} only. Paper search goes to OpenAlex.

• NCBI E-utilities require tool and email and allow 3 requests per second without a key. With NCBI_API_KEY set, this connector allows 10 requests per second.

• Europe PMC calls are capped at 5 requests per second.

• DOAJ's API docs allow a burst of five requests if the average stays at 2 per second. This connector spaces every DOAJ call by 500 ms and does not burst.

• OpenAlex's current authentication page says 10 requests per second with no key and 30 with a free key. Semantic search is 1 request per second. This connector does not call semantic search, and it does not sign up for a key.

• Retries run on 429, 5xx, timeout, and network errors, with bounded backoff and jitter, up to 3 attempts. Other 4xx responses, HTML bodies, and redirects are not retried. Redirects are refused, including a redirect toward a PDF.

• The cache and the inbound window live in the process. They disappear on exit.

• search_source and get_paper report a single source, so a failure of that source fails the call. get_paper_by_doi returns not found when both Crossref and OpenAlex miss.

• Year filters drop records that have no year. Open-access filters drop records the source did not mark open.

• Title dedupe lowercases, strips punctuation and diacritics, and collapses whitespace. Two different DOIs are never merged.

Running the tests

The tests use mocked upstream responses. They need no API key and make no network calls to the paper sources.

npm ci
npm test        # unit and tool tests (vitest)
npm run ci      # typecheck, lint, tests, and build

At the time of this commit, npm test reports 49 passing tests.

Author

Issah Abubakari (@si-essence).

This connector is also listed on Bot Essentials.

Licence

MIT. See LICENSE. The data licences above are separate from the MIT licence on this code.