cern-inspire-mcp-server

@cyanheads/cern-inspire-mcp-server

Search INSPIRE-HEP papers, authors, experiments, HEPData records; get citation metrics and BibTeX via MCP. STDIO or Streamable HTTP.

8 Tools • 1 Literature Resource Template • 1 Agent Skill

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.

Agent skill

cern-inspire-guide covers identifier routing, query syntax, and research workflows. Plugin installs, npm, Docker, and the Claude Desktop bundle include it. MCP clients can discover it through skills/list or read skill://cern-inspire-guide/SKILL.md from resources/list.

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; positive integer size (default 10, clamped to 100), paged by page
• Only the first 10,000 results of a query are reachable: page × effective 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 contributors; pass nextAuthorOffset to continue. Entries retain recorded roles (such as editor or supervisor); an absent role stays unknown. authorCount retains INSPIRE's count, falling back to the available contributor-list length
• documents lists public attached-document URLs with recorded filename, description, material, and full-text status; hidden and URL-less entries are omitted. Files are not downloaded. External urls remain separate; citingQuery and referencesQuery feed cern_inspire_search_literature
• hepdata.status is available, none, or lookup_failed, with recordDoi, latestVersion, tableCount, and hepdataUrl when available; extra HEPData records appear in hepdata.otherRecords

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; positive integer size (default 10, clamped to 50), 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); positive integer limit (default 5, clamped to 25)
• 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); positive integer limit (default 5, clamped to 25)
• 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; positive integer size (default 10, clamped to 50), 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 contributors, their recorded roles, and public attached-document links
• Takes a recid only; use the tool for arXiv IDs, DOIs, or further contributor 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:

• Positive integer result budgets above the ceiling succeed with a notice stating requested and effective values: literature 100, HEPData and citation export 50, author and experiment search 25. Defaults stay unchanged; zero, negative, and fractional budgets fail. Paging and the 10,000-result window use the effective size
• 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 empty recognized field clauses (a:, a: not, or a:"", including whitespace-only quoted values) 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).
• Selection checks cost an extra request. Literature search verifies filtered selections and later pages; export verifies filtered first pages and all later pages. This prevents INSPIRE's reference fallback from bypassing filters or repeating exhausted results. A required verification failure fails the call; unfiltered first pages keep one request
• 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

Connect to the hosted instance, no install:

claude mcp add --transport http cern-inspire-mcp-server 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:

claude mcp add cern-inspire-mcp-server -- npx -y @cyanheads/cern-inspire-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "cern-inspire-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/cern-inspire-mcp-server"]
    }
  }
}

No API key is needed. For Docker or a source build, see Running the server.

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

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

git clone https://github.com/cyanheads/cern-inspire-mcp-server.git
cd cern-inspire-mcp-server && bun install
cp .env.example .env
# Optional: change transport, logging, or session settings in .env

• 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

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/cern-inspire-mcp-server:latest

The image defaults to HTTP transport, stateless sessions, and logs at /var/log/cern-inspire-mcp-server. For an MCP client using stdio, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/cern-inspire-mcp-server:latest"]. Build locally with docker build -t cern-inspire-mcp-server .; add --build-arg OTEL_ENABLED=false to omit the OpenTelemetry peers.

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.