<!-- DOMAIN-README-BADGES-START --> <!-- An optional project logo or header line above the title; kept across copier update. --> <!-- DOMAIN-README-BADGES-END -->

Scholar MCP

<!-- mcp-name: io.github.pvliesdonk/scholar-mcp -->

Scholarly papers, patents, books, standards and PDF conversion

Documentation | Config wizard | PyPI | Docker

<!-- DOMAIN-README-PITCH-START -->

29 tools, organised by scholarly source type.

Source domains

• Papers: full-text search with year/venue/field/citation filters; single-paper lookup by DOI, S2 ID, arXiv ID, ACM ID, or PubMed ID; author profile and name search; forward citations, backward references, BFS graph traversal, shortest-path bridge discovery; recommendations from positive/negative examples; BibTeX/CSL-JSON/RIS citation generation with OpenAlex venue enrichment.
• Patents: search across 100+ patent offices via EPO OPS with CPC/applicant/inventor/jurisdiction filters; bibliographic, claims, description, family, legal, and citations sections; NPL-to-paper resolution via Semantic Scholar and paper-to-patent citation discovery. EPO credentials are optional; other domains work without them.
• Books: Open Library search by title/author/keywords, no API key required; lookup by ISBN-10/13 or by Open Library work/edition ID; subject-based recommendations sorted by popularity; Google Books excerpts and preview links; WorldCat permalinks for library discovery; cover image caching. Papers with an ISBN in externalIds are automatically enriched with publisher, edition, cover URL, and subject data from Open Library.
• Standards: identifier resolution, search, and metadata retrieval for NIST, IETF, W3C, and ETSI standards, with optional full-text fetch and Markdown conversion via docling. Tier 2 ISO, IEC, IEEE, Common Criteria (CC), and CEN/CENELEC metadata (including ISO/IEC/IEEE joint standards and the CC ↔ ISO/IEC 15408 cross-link) is synced locally via sync-standards. ISO, IEC, IEEE have a live-fetch fallback for unsynced identifiers; CC and CEN have no live API and require a sync first. Citations matching standards patterns (RFC, ISO, NIST SP, IEEE, EN, CC) are automatically enriched with structured standard_metadata including identifier, title, body, status, and full-text URL when available (see docs/use/standards.md).

Cross-cutting

• Enrichment pipeline: phased enrichment from multiple sources: OpenAlex (OA status, affiliations, funders, concepts), CrossRef (publisher, page ranges, container titles), Google Books (preview links, excerpts), and Open Library (book metadata). Runs automatically on paper and book results.
• PDF conversion: download open-access PDFs and convert to Markdown via docling-serve, with optional VLM enrichment for formulas and figures; automatic fallback to ArXiv, PubMed Central, and Unpaywall when Semantic Scholar has no OA link; direct URL download for PDFs found elsewhere; converted text is paged so large documents fit in MCP responses.
• Intelligent caching: SQLite-backed cache with per-table TTLs (30 days for papers/authors, 7 days for citations/references) and identifier aliasing.

Coverage by domain

Per-domain depth is uneven. Papers currently have the richest tool surface (citation graph, recommendations, cross-referencing to all three other domains); standards are the leanest. That reflects public data availability, not a value hierarchy: writing a paper typically needs all four source types for citations and prior art. Parity work is tracked in GitHub issues and milestones; the roadmap shows intent, not a completeness commitment.

<!-- DOMAIN-README-PITCH-END -->

Does it fit?

What the server can reach, what it changes and who gets in is set out in the security model; the block below says who it serves and where it stops.

<!-- DOMAIN-README-FIT-START -->

With this server mounted in an MCP client (Claude, etc.), you can:

• Survey a field: "Find the 20 most-cited papers on graph neural networks from 2020 to 2024 and draft a literature review outline." Composes search_papers + get_citations + enrich_paper.
• Trace a citation path: "What's the shortest citation path from 'Attention is All You Need' to 'RLHF for dialogue agents'?" Uses find_bridge_papers + get_citation_graph.
• Cross-reference prior art: "For this patent family, list academic papers it cites and any books or standards that show up in the description." Composes get_patent + batch_resolve + standards/book enrichment.
• Generate a bibliography: "Emit BibTeX for these 30 DOIs with OpenAlex venue data." Uses generate_citations.
• Look up a standard: "What's the latest status of RFC 9000, and fetch the Markdown full text." Uses resolve_standard_identifier + get_standard.

It reaches public scholarly metadata and open-access full text; it doesn't get past paywalls, and paywalled standards (ISO, IEC, IEEE) come back as metadata only. Patent tools need your own EPO OPS credentials.

<!-- DOMAIN-README-FIT-END -->

Quick start

Pick the client you use. Each line installs the released version; the Get started tutorials carry on from there.

Claude Desktop. Download the .mcpb bundle from the releases page and open it with Claude Desktop (or Settings › Extensions › Advanced settings › Install Extension…). Claude Desktop asks for the required settings itself. Tutorial.

Claude Code. Two commands inside Claude Code; the second asks for a scope. Tutorial.

/plugin marketplace add pvliesdonk/claude-plugins
/plugin install scholar-mcp@pvliesdonk

A client that runs a command (stdio). To register it in Claude Code, see the Claude Code tutorial.

uv tool install "pvliesdonk-scholar-mcp"
scholar-mcp serve

A server for remote clients (streamable HTTP). A remote server connects the clients.

docker run --rm -p 8000:8000 --env-file .env ghcr.io/pvliesdonk/scholar-mcp:latest

A compose.yml ships at the repository root and runs as-is: copy .env.example to .env, then docker compose up -d. Deploy covers authentication, OIDC, a reverse proxy and system packages (.deb/.rpm on the releases page). The server answers /health and /health/ready outside the MCP mount, and its get_server_info tool reports the running version.

<!-- DOMAIN-README-EXTRAS-START -->

• [all]: every production feature in one extra; the Linux packages and the Claude Desktop bundle install it.
• [debug]: adds the remote debugger (debugpy); see Remote debugging.

The base package already carries FastMCP through fastmcp-pvl-core, so pip install pvliesdonk-scholar-mcp is enough to run scholar-mcp serve. The older [mcp] extra is kept so existing install commands keep working; it adds nothing beyond the base package.

<!-- DOMAIN-README-EXTRAS-END -->

Configuration

Everything is configured through environment variables with the SCHOLAR_MCP_ prefix. The ones most installs set:

<!-- GENERATED-ENV-TABLE-DOMAIN-START — generated by scripts/gen_config_surface.py; do not edit -->

| Variable | Default | Required | Description | |---|---|---|---| | SCHOLAR_MCP_READ_ONLY | true | No | When true, write-tagged tools (PDF download and conversion cache writes) are hidden. Set false to enable them. | | SCHOLAR_MCP_S2_API_KEY | (none) | No | Semantic Scholar API key. Optional but strongly recommended: a key has an introductory 1 req/s allowance; anonymous users share capacity and may be throttled. Request one at https://www.semanticscholar.org/product/api#api-key-form. | | SCHOLAR_MCP_DOCLING_URL | (none) | No | Base URL of a running docling-serve instance for PDF conversion (such as http://localhost:5001). When unset, PDF conversion tools return an error. | | SCHOLAR_MCP_CACHE_DIR | /data/scholar-mcp | No | Directory for the SQLite cache database (cache.db) and downloaded PDFs (pdfs/, md/). | | SCHOLAR_MCP_CONTACT_EMAIL | (none) | No | Contact email for the OpenAlex polite pool (improves rate limits). Also enables Unpaywall lookups as a PDF fallback source. |

<!-- GENERATED-ENV-TABLE-DOMAIN-END -->

Every variable the server reads, the shared ones included, is in the configuration reference; .env.example lists the same surface in copy-paste form, and the config wizard writes one for your deployment.

Documentation

• Security model: what the server can reach, what it changes and who gets in.
• Get started: a first success with your client.
• Deploy: Docker, authentication, OIDC, reverse proxy.
• Use: the features, for real tasks.
• Reference: configuration, tools, resources, prompts, command line.
• Upgrade: release channels, and what an upgrade changes for your clients and your data.
• Contribute: local development, secrets, where a fix belongs; CONTRIBUTING.md and SECURITY.md at the root.

Design decisions

<!-- DOMAIN-README-DESIGN-START -->

• Domain logic apart from the MCP layer. The upstream clients (Semantic Scholar, OpenAlex, EPO, Open Libr