cern-inspire-mcp-server

Public Hosted Server: https://cern-inspire.caseyjhand.com/mcp

Overview

High-energy-physics literature from INSPIRE-HEP and the HEPData tables behind it. Search papers, authors, and experiments, compute citation summaries and h-indices, export BibTeX or LaTeX, and find the record holding a paper's numerical data.

Tools

Resources

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

Related MCP server: cern-opendata-mcp-server

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 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; a reversed year range fails as invalid_year_range

• Hits carry recid, title, first author, date, citation counts, arXiv ID, DOI, publication, and a 300-character abstract snippet; the page also returns totalCount, nextPage, and appliedFilters, and a notice flags queries 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/ins<recid> URL; resolvedAs names the form that matched, and a miss fails as paper_not_found. A merged recid returns the surviving record, with mergedFrom naming the recid asked for

• max_authors (default 25, capped at 500) and author_offset (default 0) page through authors; pass nextAuthorOffset to continue. authorCount is INSPIRE's full count

• hepdata.status is available, none, or lookup_failed, with recordDoi, latestVersion, tableCount, and hepdataUrl when available; extra HEPData records appear in hepdata.otherRecords. 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), with the same document_types, subjects, year_from, year_to, and sort as search; reversed years fail as invalid_year_range

• format is bibtex (default), latex-eu, or latex-us; size 1–50 (default 10), paged by page within the first 10,000 matches (beyond that, beyond_result_window)

• Entries arrive verbatim from INSPIRE, each with its texkey; truncated and nextPage signal more results, and appliedFilters echoes the selection

cern_inspire_search_authors tool

• A name or one identifier (BAI, ORCID, INSPIRE ID, author recid); limit 1–25 (default 5)

• matchedAs is orcid, inspire_id, bai, or recid (exact match), or name (free-text search returning ranked candidates to choose from)

• Profiles carry recid, bai, ORCID, positions (with an institutionRecid that affid:N takes for the institution's papers), 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, such as affid:902725 for an institution's papers); otherwise missing_target, and a name passed as author fails as author_not_identifier

• Narrow with document_types, subjects, year_from, year_to, and exclude_self_citations

• Returns 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

• citationsByYear is omitted, with a notice, when year_from, year_to, or exclude_self_citations is set, when INSPIRE does not return it, or for queries matching more than about 150,000 records

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 (each record's own hepdata.net page); 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; no upstream call

inspire://literature/{recid} resource

• The cern_inspire_get_paper dossier as application/json, with the first 25 authors

• Takes a recid only; use the tool for arXiv IDs, DOIs, or further author pages. A merged recid serves the surviving record, with mergedFrom

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:

• Paces requests to 12 per 5 s, under INSPIRE's limit of 15, with a cooldown after a 429; a call that can't start in time fails as pacer_shed with a retryAfter

• 55 s budget per tool call, including queue wait and up to 2 retries

• Requests select only the fields a tool returns; author email addresses are never requested

• Forgiving inputs: paper identifiers accept arXiv: / doi: prefixes, version suffixes, and arxiv.org, doi.org, or inspirehep.net URLs; author identifiers accept an orcid.org URL

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

• 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; 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"

• Titles and abstracts as text: publisher HTML, JATS, and MathML become plain text (σ_γ, ^{23}Na(n,γ)), with LaTeX left as published and citation export entries verbatim

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.

• 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 the server never calls it. 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 mostly doesn't fail. Literature search, citation summaries, and citation export reject only empty field clauses (a: or a: not) as invalid_query; give each field a value (a Witten). Otherwise an unparsed operator widens or empties the match; 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.

• Shared request queue. All callers of one server process share one queue under INSPIRE's 15 requests per 5 s per address, so a burst can delay or shed other calls with a retryable rate-limit error.

Getting started

Public Hosted Instance

A public instance is available at https://cern-inspire.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "cern-inspire-mcp-server": {
      "type": "streamable-http",
      "url": "https://cern-inspire.caseyjhand.com/mcp"
    }
  }
}

Every caller of the hosted instance shares one INSPIRE request budget of 12 request starts per 5 seconds. For sustained use, run your own instance.

Self-Hosted / Local

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:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun 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 devcheck
bun run test

License

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