cern-inspire-mcp-server

Overview

High-energy-physics literature from INSPIRE-HEP, including its index of HEPData measurement records. Search papers, authors, and experiments, read a paper's full record, compute citation summaries and h-indices, export BibTeX or LaTeX entries, and find the HEPData record that holds a paper's numerical tables. Runs as a stdio process or a local Streamable HTTP server.

Tools

Resources

The same record is reachable through cern_inspire_get_paper for clients that don't surface resources.

Capability reference

cern_inspire_search_literature _tool

• INSPIRE query syntax or free text, with sort (relevance, mostrecent, mostcited), document_types and subjects (up to 4 values each, all of which must hold), and year_from / year_to; size 1–100 (default 10), paged by page
• Only the first 10,000 results of a query are reachable: page × size beyond that fails as beyond_result_window, and a reversed year range as invalid_year_range
• Hits carry recid, title, first author, date, citation counts, arXiv ID, DOI, publication, and a 300-character abstract snippet; totalCount, nextPage, and appliedFilters come back with the page, and a notice flags any query matching over 100,000 records

cern_inspire_get_paper _tool

• paper takes a recid, arXiv ID, DOI, inspirehep.net literature URL, or HEPData ins<recid> / hepdata.net record URL; resolvedAs names the form that matched, and a miss fails as paper_not_found
• max_authors 0–500 (default 25) caps the author list; authorCount always gives the full number
• hepdata.status is available, none, or lookup_failed, with recordDoi, latestVersion, tableCount, and hepdataUrl when available; citingQuery and referencesQuery feed cern_inspire_search_literature

cern_inspire_export_citations _tool

• Any literature query (recid:451647 or arxiv:1207.7214 for named papers); format is bibtex (default), latex-eu, or latex-us; size 1–50 (default 10)
• Entries arrive verbatim from INSPIRE, each with its texkey; truncated is set when more papers matched than size

cern_inspire_search_authors _tool

• A name or one identifier (BAI, ORCID, INSPIRE ID, author recid); limit 1–25 (default 5)
• matchedAs reports the route: orcid, inspire_id, bai, and recid match exactly, while name runs a free-text search whose ranked candidates are returned for the caller to choose from
• Profiles carry recid, bai, ORCID, positions, advisors, arXiv categories, awards, and a literatureQuery selecting the person's papers

cern_inspire_get_citation_summary _tool

• Exactly one of author (BAI, ORCID, INSPIRE ID, or author recid) or query (any literature query); otherwise missing_target, and a name passed as author fails as author_not_identifier
• document_types, subjects, and year_from / year_to narrow every figure; exclude_self_citations recounts without self-citations
• h-index, citation totals and averages, and paper counts in the buckets 0, 1–9, 10–49, 50–99, 100–249, 250–499, 500+, each for all citeable and for published papers

cern_inspire_search_experiments _tool

• An experiment, collaboration, accelerator, or facility name, an INSPIRE legacy name (CERN-LHC-CMS), or an experiment recid (digits only); limit 1–25 (default 5)
• Records carry the accelerator, host institutions, collaboration, lifecycle dates, ongoing (omitted when INSPIRE records neither state), INSPIRE's paper count, and a literatureQuery for cern_inspire_search_literature or cern_inspire_get_citation_summary

cern_inspire_search_hepdata _tool

• Free text or INSPIRE syntax over HEPData submissions (collaborations.value:LHCb, literature.control_number:<recid>); sort is relevance or mostrecent; size 1–50 (default 10), within the same 10,000-result window
• Records carry paperRecids, collaborations, keywords (reactions, observables, centre-of-mass energies), recordDoi, latestVersion, tableCount, and hepdataUrl; table values are not returned

cern_inspire_list_reference _tool

• topic: search_syntax, identifiers, document_types, subjects, citation_buckets, or hepdata
• Static term / meaning / example entries with no upstream call

inspire://literature/{recid} _resource

• The cern_inspire_get_paper dossier for one recid as application/json, listing the first 25 authors
• Takes a recid only; use the tool for arXiv IDs, DOIs, or a higher author cap

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

INSPIRE-specific:

• One process-wide pacer under INSPIRE's published 15 requests per 5 s: 12 request starts per 5 s, at most 4 in flight, and a shared cooldown after a 429 that starts at 5 s and doubles on each consecutive 429, up to 30 s
• One 55 s budget per tool call covers queue wait, up to 2 retries, and every request the call makes; a request that can't start in time fails at once as pacer_shed with a retryAfter
• JSON requests select only the fields a tool returns, under an 8 MiB response ceiling and a strict query-parameter allowlist, since INSPIRE silently ignores parameters it doesn't know; author email addresses are never requested
• Forgiving inputs: paper identifiers accept an arXiv: or doi: prefix, a version suffix, an arxiv.org, doi.org, or inspirehep.net URL, and HEPData's ins<recid>; author identifiers accept an orcid.org URL; document_types and subjects take an array or a comma-joined string in any case

Agent-friendly output:

• Chainable identifiers: hits carry recid, author profiles and experiments carry a ready literatureQuery, and cern_inspire_get_paper returns citingQuery and referencesQuery, so the next call needs no query building
• Query echo and paging state: totalCount, truncated / shown / cap, nextPage, appliedFilters, and effectiveQuery, plus a notice with next-step text on empty, capped, or suspiciously broad results
• Discriminated fields: hepdata.status, resolvedAs, matchedAs, and target.kind let callers branch on data, and typed failure reasons (paper_not_found, author_not_found, beyond_result_window, inspire_rate_limited) each carry a recovery hint
• No fabrication: a field INSPIRE leaves out stays absent and prints as "Not available" or "not recorded"; upstream strings are escaped in the text output and kept verbatim in structuredContent

Data and licensing

• INSPIRE-HEP metadata is mostly CC0 under INSPIRE's terms of use; credit INSPIRE when you reuse it.
• HEPData records are CC0; cite the HEPData record DOI (recordDoi) when you reuse the data.
• INSPIRE allows 15 requests per 5 seconds per address, and the server paces its own requests under that limit.
• This is an independent project, not affiliated with or endorsed by INSPIRE-HEP, HEPData, or CERN.

Known limitations

• No HEPData table values. hepdata.net's bot challenge refuses the server's User-Agent, so tools that read hepdata.net directly are deferred. cern_inspire_get_paper and cern_inspire_search_hepdata return the record DOI and the hepdata.net page where the values are read.
• Malformed INSPIRE syntax doesn't fail. An unparsed operator widens or empties the match instead; zero hits or a very large totalCount usually means a syntax slip (cern_inspire_list_reference topic search_syntax).
• 10,000-result window. Only the first 10,000 results of a query are reachable; narrow the query to reach the rest.
• One request queue per process, one rate limit per address. Every caller of a server process shares one queue under INSPIRE's 15 requests per 5 s, so on a shared deployment one client's burst can delay or shed everyone else's calls with a retryable rate-limit error. A hosted deployment needs a per-client rate limit in front of /mcp, and should run one replica per egress IP, since INSPIRE counts requests per address; a per-caller share inside the server waits on the framework (cyanheads/mcp-ts-core#618).

Getting started

Add the following to your MCP client configuration file. No API key is needed.

{  "mcpServers": {    "cern-inspire-mcp-server": {      "type": "stdio",      "command": "bunx",      "args": ["@cyanheads/cern-inspire-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with npx (no Bun required):

{  "mcpServers": {    "cern-inspire-mcp-server": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@cyanheads/cern-inspire-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with Docker:

{  "mcpServers": {    "cern-inspire-mcp-server": {      "type": "stdio",      "command": "docker",      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cern-inspire-mcp-server:latest"]    }  }}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• Nothing else: INSPIRE-HEP's API is public and keyless.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/cern-inspire-mcp-server.git

2. Navigate into the directory:

cd cern-inspire-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env# edit .env to change the transport, logging, or session settings

Configuration

The server has no settings of its own: INSPIRE needs no key, and the request pacing is fixed in code. These framework variables cover most deployments.

See .env.example for the full list of framework overrides.

Running the server

Local development

• Build and run the production version:

  sh

  # One-time buildbun run rebuild
  # Run the built serverbun run start:http# orbun run start:stdio

• Run checks and tests:

  sh

  bun run devcheck  # Lints, formats, type-checks, and morebun run test      # Runs the test suite

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Every INSPIRE request goes through InspireService, with the call opened by beginCall(ctx); handlers never fetch directly
• Register new tools and resources in the barrels at src/mcp-server/tools/definitions/index.ts and src/mcp-server/resources/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheckbun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.