academic-tools-mcp

An MCP server that gives LLM agents lean, focused tools for working with academic papers. Built on FastMCP.

Look up paper metadata, authors, abstracts, citations, and BibTeX entries. Download and read full paper PDFs section-by-section. Explore reference and citation graphs. Cross-reference with Wikipedia.

Data Sources

All API responses are cached locally. Multiple tool calls for the same paper = one API hit. Concurrent calls for the same paper are coalesced into a single fetch (request single-flight), transient failures (5xx, 429, timeouts) get one transparent retry, and definitive 404s are negative-cached for 24 hours so retry-happy agents don't burn rate budget on guaranteed misses.

Setup

Requires Python 3.11+ and uv.

git clone https://github.com/hunter-heidenreich/academic-tools-mcp.git
cd academic-tools-mcp
uv sync
cp .env.example .env   # then edit .env with your values

Configuration

All configuration is via environment variables in .env. Nothing is required to get started, but some variables unlock higher rate limits.

Usage

With Claude Code

Add to your MCP config (~/.claude/claude_code_config.json):

{
  "mcpServers": {
    "academic-tools": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/academic-tools-mcp", "python", "-m", "academic_tools_mcp.server"]
    }
  }
}

Standalone

uv run python -m academic_tools_mcp.server

FastMCP CLI

uv run fastmcp run src/academic_tools_mcp/server.py:mcp

Tools

Papers (unified, auto-routed)

Pass an arXiv ID (2301.00001, hep-th/9901001) or any DOI — including bioRxiv/medRxiv (10.1101/...), ACL Anthology (10.18653/v1/...), or generic publisher DOIs. Each response carries a _source field ("arxiv" / "biorxiv" / "openalex") so you know which provider answered and which fields to expect. arXiv IDs always route to arXiv; bioRxiv DOIs route to bioRxiv; everything else (including ACL) routes to OpenAlex.

Authors

Accepts OpenAlex author IDs (from get_paper_authors) or ORCIDs.

PDF pipeline (unified)

All four tools accept any identifier (arXiv ID, DOI, or freeform label) and auto-route to the correct provider's cache namespace. For papers not hosted on arXiv/ACL/bioRxiv, fetch the PDF yourself and hand it to import_paper — see Manual import below.

References and citations (DOI required)

For citations, follow the count-then-page pattern: call get_paper_citations_count first to see the total, then page through with page and page_size. For references the source="auto" default does the survey for you on the first call. Paginated responses include _source (on references) and has_more so agents know which shape to expect and when to stop. This prevents token blowouts on papers with long bibliographies or many citations.

Source trade-off for references: Crossref returns structured reference metadata (author, title, year, journal, DOI) when publishers deposit it; quality varies. OpenCitations aggregates from Crossref, PubMed, DataCite, OpenAIRE, and JaLC — it may have entries Crossref lacks, but returns DOI-to-DOI links only (no bibliographic metadata).

Manual import

For PDFs outside arXiv/bioRxiv/ACL, fetch the file yourself (browser, curl, publisher portal, institutional proxy) and then call import_paper — the server deliberately does not download arbitrary URLs.

After importing a PDF, use the unified pipeline tools (convert_paper → get_paper_sections → get_paper_section) with the same identifier. Markdown imports skip the conversion step and go straight to get_paper_sections / get_paper_section.

Provider-aware routing: if the identifier is an arXiv ID, bioRxiv DOI, or ACL DOI, the file is stored in that provider's cache namespace automatically. A subsequent download_pdf("2301.00001") will find an already-imported PDF — no duplicates.

Wikipedia

PDF Pipeline

The PDF-to-markdown pipeline converts downloaded PDFs into section-level markdown that agents can read piece by piece, avoiding token blowouts from dumping entire papers into context.

The pipeline is converter-agnostic. Set PDF_CONVERTER in .env to choose your backend:

# Named backends
PDF_CONVERTER=mineru          # default — https://github.com/opendatalab/MinerU
PDF_CONVERTER=marker          # https://github.com/datalab-to/marker

# Custom command template — use {input} and {output_dir} placeholders
PDF_CONVERTER=my-tool --in "{input}" --out "{output_dir}"

If your converter lives in a virtualenv, set PDF_CONVERTER_VENV:

PDF_CONVERTER_VENV=~/.venvs/mineru

The converter must accept a PDF input path and an output directory, and produce one or more .md files in that directory. The pipeline finds the markdown file automatically.

Note: PDF converters are external tools with their own licenses. MinerU is AGPL-3.0; Marker is GPL. This project invokes them as CLI subprocesses and does not link or import their code. The PDF pipeline is entirely optional — all metadata, BibTeX, and citation tools work without it.

Installing MinerU (example setup)

python -m venv ~/.venvs/mineru
source ~/.venvs/mineru/bin/activate
pip install mineru

Then in .env:

PDF_CONVERTER=mineru
PDF_CONVERTER_VENV=~/.venvs/mineru

Caching

API responses and downloaded files are cached under .cache/:

.cache/
  openalex/works/          # OpenAlex work objects (JSON)
  openalex/authors/        # OpenAlex author objects (JSON)
  arxiv/papers/            # arXiv paper entries (JSON)
  arxiv/pdfs/              # Downloaded PDFs
  arxiv/markdown/          # Converted markdown
  arxiv/sections/          # Section indices (JSON)
  biorxiv/papers/          # bioRxiv paper entries (JSON)
  biorxiv/pdfs/            # Downloaded PDFs
  biorxiv/markdown/        # Converted markdown
  biorxiv/sections/        # Section indices (JSON)
  acl_anthology/pdfs/      # Downloaded PDFs
  acl_anthology/markdown/  # Converted markdown
  acl_anthology/sections/  # Section indices (JSON)
  crossref/works/          # Crossref work objects (JSON)
  opencitations/references/# OpenCitations reference lists (JSON)
  opencitations/citations/ # OpenCitations citation lists (JSON)
  wikipedia/summaries/     # Wikipedia page summaries (JSON)
  manual/pdfs/             # Manually imported PDFs
  manual/markdown/         # Converted markdown
  manual/sections/         # Section indices (JSON)

Cache keys are SHA-256 hashes of canonical identifiers. Writes are atomic (temp file + os.replace) so a crash mid-write can't leave a corrupt entry; corrupt entries from earlier versions self-heal on read. Positive entries have no expiration — delete .cache/ to start fresh. Negative entries (definitive 404s) live in a sibling _neg/ subdirectory under each entity with a 24-hour TTL, so retry-happy agents don't repeatedly hit the network for known-bad identifiers but newly-registered DOIs still surface within a day.

Development

uv sync                          # Install dependencies
uv run pytest -v                 # Run all tests (485 tests)
uv run pytest tests/test_bibtex.py -v   # Run one test file
uv run pytest -k "test_particle" -v     # Run tests matching a pattern

Architecture

server.py (21 MCP tools; FastMCP lifespan closes pooled clients on shutdown)
  │
  ├── API clients          openalex.py, arxiv.py, biorxiv.py,
  │                        crossref.py, opencitations.py, wikipedia.py,
  │                        acl_anthology.py
  │
  ├── PDF + content        manual.py         (local-file import)
  │                        papers.py         (PDF → markdown → sections;
  │                                           global single-conversion lock;
  │                                           in-paper find_in_markdown)
  │                        cache_search.py   (BM25 over cached markdown)
  │                        bibtex.py         (BibTeX generation)
  │                        _pdf_download.py  (streaming download helper)
  │
  └── Shared infrastructure (every API client routes through these)
        _http.py           one-shot retry, structured errors, backpressure
        _clients.py        per-provider pooled httpx.AsyncClient
        _singleflight.py   concurrent same-key callers coalesce to one fetch
        cache.py           atomic file cache with negative-cache (24h TTL)

Key design decisions:

• Lean responses. Tools return only what's needed — not the full API response. An agent calling get_paper_authors doesn't get flooded with unrelated metadata.
• One tool per job, auto-routed. The four core paper tools (get_paper_metadata, get_paper_authors, get_paper_abstract, get_paper_bibtex) dispatch on identifier shape rather than forcing the agent to pick between arXiv/bioRxiv/OpenAlex families. Provider-native fields are preserved and tagged with _source.
• Batch where it matters. get_papers_metadata collapses N parallel singletons into one HTTP call per 50 OpenAlex DOIs (/works?filter=doi:...|...) plus concurrent fan-out for arXiv / bioRxiv — designed for reference-graph enrichment.
• One API hit per entity. All tools for a given DOI share one cached response. Concurrent same-key callers are coalesced by single-flight to one fetch.
• Per-provider concurrency. Each provider has its own concurrency cap (arxiv=1 single-connection rule, openalex=4, crossref=3, etc.) — multiple GETs run in flight up to the cap while a brief gap-lock enforces inter-start spacing. Reference-graph traversals are dramatically faster than the previous serialise-everything model.
• Persistent connections, transparent retries. Each provider holds one pooled httpx.AsyncClient so TCP+TLS handshakes are reused. Transient failures (5xx, 429, timeouts, network errors) get one in-process retry that honours Retry-After (capped) before surfacing to the agent.
• Burst caps with structured backpressure. Each provider refuses to stack more than 5 concurrent callers behind its rate-limit gap. The 6th gets {error, retryable: True, backpressure: True} immediately so the agent learns to slow down rather than waiting silently.
• Negative caching for definitive 404s. Known-bad identifiers are cached for 24h so retries don't burn rate budget; transient errors are NOT cached.
• Streaming PDF downloads with size guard. PDFs stream chunked to a temp file with atomic rename — peak memory = 64 KiB, not 2× the PDF — and abort mid-stream if MAX_PDF_BYTES (default 200 MB) is exceeded. Force-refresh cascades: re-downloading drops the cached markdown + sections so the next conversion picks up the new bytes.
• Single-conversion lock for PDFs. At most one PDF→markdown subprocess runs at a time across the whole server; concurrent callers get a busy error with what's running and how long it's been going.
• Count-then-page for large data. Citation and reference tools expose a _count tool so agents can check sizes before fetching. get_paper_references(source="auto") does the survey for you.
• Provider-aware routing. Manual imports auto-detect identifier types and store in the correct provider's cache, preventing duplicates.
• Subprocess isolation for PDF converters. The PDF pipeline shells out to external tools rather than importing them, keeping the dependency tree light and avoiding license entanglement.
• Pre-computed aggregates. List responses include counts (author_count, topic_count, total_sections, etc.) so agents don't need follow-up calls to check sizes.
• Structured error hints. Error responses include a suggestion field with recovery guidance (e.g. which search tool to try).

Versioning

This project uses calendar versioning: each release is named for the day it
was cut — YYYY.MM.DD, tagged vYYYY.MM.DD in git (a rare same-day re-release
takes a .postN suffix). See CHANGELOG.md for the release
history.

License

MIT — see LICENSE.