paperbase-mcp

# paperbase-mcp A research-grade MCP server for academic literature. Composes arXiv, Semantic Scholar, OpenAlex, and (optionally) [unarXive](https://huggingface.co/datasets/saier/unarXive) into a single tool surface for finding papers, walking citation graphs, and generating BibTeX — without leaving your chat. No PDF downloads, no local PDF cache, no full-text search. If you want those, see [`arxiv-mcp-server`](https://github.com/blazickjp/arxiv-mcp-server). If you want metadata, relations, and venue-correct BibTeX, you're in the right place. ## What it looks like in Claude Desktop ``` You: Give me the 25 most-cited descendants of arXiv 1706.03762, dedup, drop self-citations, with BibTeX. Claude: [calls related_work with identifier="1706.03762", limit=25, include_self_citations=false] The top descendants of "Attention Is All You Need" are: 1. BERT (Devlin et al., 2018) — 80k citations, NAACL 2. GPT-3 (Brown et al., 2020) — 30k citations, NeurIPS 3. T5 (Raffel et al., 2020) — 15k citations, JMLR … BibTeX for all 25 below: @inproceedings{devlin2018bert, title = {BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding}, author = {Jacob Devlin and ...}, booktitle = {NAACL}, year = {2018}, … } … ``` Drop into your own `.bib` and keep working. ## Install Add the server to your MCP client config: ```json { "mcpServers": { "paperbase": { "command": "uvx", "args": ["paperbase-mcp"], "env": { "PAPERBASE_MAILTO": "you@example.com" } } } } ``` The mailto is required: it goes into the User-Agent and into OpenAlex's polite-pool query param. Snippets for Claude Desktop, Cursor, Codex, and Gemini CLI are in [docs/install.md](docs/install.md). ## Tools | Tool | What it does | |---|---| | `search_papers` | Keyword search across S2 (with arXiv fallback). `ranking` is "relevance" or "date". | | `find_paper` | Resolve an arXiv ID / DOI / S2 id / URL / title to one Paper with field-level provenance. | | `related_work` | References + citations, deduped, ranked, with venue-correct BibTeX attached. | | `citation_graph` | Bounded walk over cites / cited-by, with `truncated` flag when the cap is hit. | | `author_papers` | Recent papers + venues for a (disambiguated) author. | | `paper_sections` | Parsed sections via unarXive; abstract-only if not configured. | | `bibtex_for` | BibTeX with collision-free citation keys; published venue (`@article` / `@inproceedings`) when DOI known, else arXiv preprint (`@misc`). | | `compare_papers` | Side-by-side facets for 2–5 papers. Regex-based extraction. | Every tool returns the same envelope: ``` {ok, data?, error_kind, error_message, retry_after?, upstreams_used, partial, provenance} ``` Errors never throw across the MCP boundary. `partial=true` is the soft-failure signal (one upstream was down, we returned what we could). ## Recipes Worked examples — written as the workflow, not the API: - [related-work synthesis from an arXiv ID](recipes/related-work-synthesis.md) - [most-cited descendants of a paper](recipes/citation-descendants.md) - [author venue trends over time](recipes/author-venue-trends.md) - [setting up a local unarXive index](recipes/setup-unarxive.md) (enables `paper_sections` beyond abstract-only) ## Why not just curl the APIs Four of the eight tools really are wrappers; we're honest about that. The four that aren't: - **`find_paper`** runs arXiv ‖ S2 in parallel, merges with primary-wins precedence, and emits field-level provenance — so you know whether `abstract` came from arXiv or S2. - **`related_work`** dedupes the same paper across `s2_paper_id` / `arxiv_id` / `doi`, drops self-citations by author overlap, ranks by `log1p(citations) * exp(-age/10)` with a 1.5× bump for S2's `isInfluential`, and attaches venue-correct BibTeX. - **`bibtex_for`** prefers `@inproceedings` / `@article` over `@misc` when a venue is known, generates collision-free keys, and resolves duplicates across the input list. - **`citation_graph`** is a bounded BFS with truncation signalling, so agents can adapt when they hit the cap. You can hand-write any of these in an afternoon. The server gives you that afternoon back, and it does so the same way every time. ## Behaviour notes - Per-upstream token bucket (arXiv 1 req / 3 s, S2 1 RPS, OpenAlex 8 RPS). Backs off on 429 honouring `Retry-After`. - Per-upstream circuit breaker — 3 failures opens, 60-second cool-down, one half-open probe. - SQLite cache at `~/.cache/paperbase-mcp/cache.sqlite` (XDG / Library / AppData via `platformdirs`). 2xx and 404 cached, 5xx / 429 never. - Cache TTLs: search 6h, find 7d, related/graph/author 24h, sections 7d, bibtex 30d, not-found 1h. Override any with `PAPERBASE_TTL_<NAME>`. - Missing fields stay null. The server never imputes. ## Development ``` pip install -e ".[dev]" make ci # ruff + mypy --strict + pytest ``` Fixture-backed tests via respx; no live upstream calls in the default suite. CI matrix is Python 3.11 / 3.12 / 3.13 × Linux / macOS / Windows. Read [docs/00-brief.md](docs/00-brief.md) for the design rationale and [docs/01-architecture.md](docs/01-architecture.md) for the layered internals. The reviewer-lens docs at `docs/03-review-*.md` are the honest critique passes (MCP power user, ML researcher, upstream maintainer, HN skeptic). ## License Apache-2.0.