cern-inspire-mcp-server
An MCP server that provides tools to search INSPIRE-HEP for high-energy physics papers, authors, and experiments, retrieve full paper records, export BibTeX citations, and access HEPData records. It supports filtering by document type, subject, and year, and can compute citation metrics like h-indices.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://cern-inspire.caseyjhand.com/mcpWhat its tools do
8 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Search INSPIRE-HEP papers using query syntax or free text
- Fetch full paper records by recid, arXiv ID, or DOI
- Export BibTeX or LaTeX entries for selected papers
- Find physicist profiles and citation summaries
Source and maintenance
Community listingRegistry 0.2.0
- Maintenance checked
Protocol and capabilities
- Server
- cern-inspire-mcp-server 0.2.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 8 advertised
- Resources
- 1 advertised
- Resource templates
- 2 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
8 advertised
cern_inspire_search_literature — Search INSPIRE literature
Advertised read-onlyOpen-world
Search INSPIRE-HEP papers with INSPIRE query syntax or free text, filtered by document type, subject, and year, sorted by relevance, recency, or citations. Returns one page of papers with recid, title, first author, date, citation counts, arXiv ID, DOI, publication, and an abstract snippet; pass a recid to cern_inspire_get_paper for the full record or to cern_inspire_export_citations ("recid:N") for BibTeX. Empty recognized field clauses are invalid; other malformed syntax can widen or empty the match, so check an unexpectedly broad or empty result against cern_inspire_list_reference topic search_syntax. Only the first 10,000 results of a query are reachable.
cern_inspire_search_literature input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number, starting at 1. page × effective size (after clamping) may not exceed 10,000."
},
"size": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Papers per page (positive integer, default 10; above 100 uses 100)."
},
"sort": {
"enum": [
"relevance",
"mostrecent",
"mostcited"
],
"type": "string",
"default": "relevance",
"description": "Result order: relevance (default), mostrecent, or mostcited."
},
"query": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "INSPIRE query syntax or free text. Common operators: \"a Jane.Doe.1\" or \"a Doe, J\" (author), \"t higgs boson\" (title words), \"cn atlas\" or \"collaboration:atlas\" (collaboration), \"date > 2015\", \"topcite 500+\" (cited 500+ times), \"refersto:recid:451647\" (papers citing a record), \"citedby:recid:451647\" (its references), \"j Phys.Rev.Lett.\" (journal), \"eprint 1207.7214\"; combine with and/or/not. Bare words search all fields. Empty recognized field clauses such as a: or a:\"\" (including whitespace-only quoted values) are invalid; other syntax is passed to INSPIRE without complete grammar validation. See cern_inspire_list_reference topic search_syntax."
},
"year_to": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Latest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no upper bound."
},
"subjects": {
"type": "array",
"items": {
"enum": [
"Astrophysics",
"Phenomenology-HEP",
"Theory-HEP",
"Quantum Physics",
"Unknown",
"Gravitation and Cosmology",
"Experiment-HEP",
"Theory-Nucl",
"Accelerators",
"Instrumentation",
"General Physics",
"Experiment-Nucl",
"Math and Math Physics",
"Condensed Matter",
"Computing",
"Lattice",
"Other",
"Data Analysis and Statistics"
],
"type": "string",
"description": "An INSPIRE subject category."
},
"maxItems": 4,
"description": "Restrict to INSPIRE subject categories (up to 4). Multiple values must ALL hold, not either. Values: Astrophysics, Phenomenology-HEP, Theory-HEP, Quantum Physics, Unknown, Gravitation and Cosmology, Experiment-HEP, Theory-Nucl, Accelerators, Instrumentation, General Physics, Experiment-Nucl, Math and Math Physics, Condensed Matter, Computing, Lattice, Other, Data Analysis and Statistics."
},
"year_from": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Earliest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no lower bound."
},
"document_types": {
"type": "array",
"items": {
"enum": [
"article",
"published",
"conference paper",
"thesis",
"review",
"note",
"proceedings",
"lectures",
"book chapter",
"book",
"introductory",
"activity report",
"report"
],
"type": "string",
"description": "An INSPIRE document type."
},
"maxItems": 4,
"description": "Restrict to INSPIRE document types (up to 4). Multiple values must ALL hold (published + review = published reviews), not either. Values: article, published, conference paper, thesis, review, note, proceedings, lectures, book chapter, book, introductory, activity report, report."
}
},
"additionalProperties": false
}cern_inspire_search_literature output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"papers",
"page",
"size",
"hasMore",
"totalCount",
"truncated",
"shown",
"cap",
"appliedFilters"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The page size applied."
},
"page": {
"type": "number",
"description": "The page returned."
},
"size": {
"type": "number",
"description": "The effective page size after clamping."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"beyond_result_window",
"invalid_year_range",
"invalid_query",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `beyond_result_window`: page × effective size (after clamping) exceeds the 10,000 results INSPIRE serves for one query. `invalid_year_range`: year_from is later than year_to. `invalid_query`: A recognized field clause has no value, or INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, was HTML where JSON was expected, or was invalid JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of papers on this page."
},
"notice": {
"type": "string",
"description": "Guidance on an empty, very broad, or paged result."
},
"papers": {
"type": "array",
"items": {
"type": "object",
"required": [
"recid",
"title",
"collaborations",
"documentTypes",
"citationCount",
"arxivCategories"
],
"properties": {
"doi": {
"type": "string",
"description": "First DOI, when the paper has one."
},
"date": {
"type": "string",
"description": "Earliest date INSPIRE records for the paper: YYYY, YYYY-MM, or YYYY-MM-DD."
},
"recid": {
"type": "string",
"description": "INSPIRE literature record ID; pass to cern_inspire_get_paper."
},
"title": {
"type": "string",
"description": "Title as text: publisher HTML, JATS, and MathML converted (scripts as _x or ^{xy}), LaTeX left as published."
},
"arxivId": {
"type": "string",
"description": "arXiv identifier, when the paper has one."
},
"authorCount": {
"type": "number",
"description": "Number of authors, when INSPIRE indexes the count."
},
"firstAuthor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "First author, \"Surname, Given names\"."
},
"recid": {
"type": "string",
"description": "INSPIRE author record ID, when linked; pass as query to cern_inspire_search_authors for the profile."
}
},
"description": "First author, when INSPIRE indexes one.",
"additionalProperties": false
},
"publication": {
"type": "string",
"description": "First publication reference: \"Journal Vol (Year) pages\" or its free-text form."
},
"citationCount": {
"type": "number",
"description": "Citations INSPIRE counts for the paper."
},
"documentTypes": {
"type": "array",
"items": {
"type": "string",
"description": "INSPIRE document type."
},
"description": "INSPIRE document types."
},
"collaborations": {
"type": "array",
"items": {
"type": "string",
"description": "Collaboration name."
},
"description": "Collaborations credited on the paper; empty for most non-collaboration papers."
},
"abstractSnippet": {
"type": "string",
"description": "Start of the abstract as text (arXiv-sourced when available; publisher markup converted, LaTeX left as published), up to 300 characters at a word boundary."
},
"arxivCategories": {
"type": "array",
"items": {
"type": "string",
"description": "arXiv category."
},
"description": "arXiv categories of the e-print."
},
"abstractTruncated": {
"type": "boolean",
"description": "True when the abstract continues past the snippet; cern_inspire_get_paper has it in full."
},
"citationCountWithoutSelf": {
"type": "number",
"description": "Citations excluding self-citations, when INSPIRE reports it."
}
},
"description": "One matching paper.",
"additionalProperties": false
},
"description": "The papers on this page, in the requested order."
},
"hasMore": {
"type": "boolean",
"description": "True when INSPIRE has a further page of results."
},
"nextPage": {
"type": "number",
"description": "The page number to request next, when one exists within the 10,000-result window."
},
"truncated": {
"type": "boolean",
"description": "True when more results exist beyond this page."
},
"totalCount": {
"type": "number",
"description": "Total literature records the query matched."
},
"appliedFilters": {
"type": "string",
"description": "Sort and filters applied, e.g. \"sort=mostcited; years=2012–2015\", or \"none\"."
}
},
"additionalProperties": false
}cern_inspire_search_literature annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_get_paper — Get INSPIRE paper
Advertised read-onlyOpen-world
Fetch one paper's full INSPIRE-HEP record by recid, arXiv ID, or DOI: contributors with affiliations and recorded roles, public attached-document links and identifiers, abstract, publication references, arXiv and DOI identifiers, keywords, subjects, citation counts, linked experiments, texkeys, and whether HEPData holds its numerical tables (record DOI, latest version, table count, hepdata.net link). Also returns ready-made literature queries for the papers citing it and for its references. Large collaboration papers can list thousands of authors; max_authors caps the list while authorCount gives the full number.
cern_inspire_get_paper input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"paper"
],
"properties": {
"paper": {
"type": "string",
"maxLength": 256,
"description": "INSPIRE recid (e.g. 451647), arXiv ID (1207.7214 or hep-th/9711200, with or without 'arXiv:', a version suffix, or an https://arxiv.org/abs/ or https://arxiv.org/pdf/ prefix), DOI (10.1016/…, with or without 'doi:' or an https://doi.org/ prefix; no * or ? wildcards), an https://inspirehep.net/literature/<recid> URL, or HEPData's ins<recid> form, alone or in an https://www.hepdata.net/record/ins<recid> URL. Up to 256 characters."
},
"max_authors": {
"type": "integer",
"default": 25,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Most contributors to list (nonnegative integer, default 25; values above 500 use 500). Zero lists no contributors. The full count is always in authorCount."
},
"author_offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based starting position in the normalized contributor list (default 0). Use nextAuthorOffset from the previous page."
}
},
"additionalProperties": false
}cern_inspire_get_paper output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"recid",
"resolvedAs",
"title",
"alternateTitles",
"authorCount",
"authorOffset",
"authors",
"collaborations",
"experiments",
"publications",
"arxivCategories",
"dois",
"reportNumbers",
"keywords",
"subjects",
"documentTypes",
"citationCount",
"texkeys",
"documents",
"urls",
"licenses",
"inspireUrl",
"citingQuery",
"referencesQuery",
"hepdata",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The max_authors cap applied."
},
"core": {
"type": "boolean",
"description": "True when INSPIRE classes the paper as core HEP, when recorded."
},
"date": {
"type": "string",
"description": "Earliest date INSPIRE records for the paper: YYYY, YYYY-MM, or YYYY-MM-DD."
},
"dois": {
"type": "array",
"items": {
"type": "string",
"description": "A DOI."
},
"description": "DOIs of the paper."
},
"urls": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "Link URL."
},
"description": {
"type": "string",
"description": "Link description, when given."
}
},
"description": "One external link.",
"additionalProperties": false
},
"description": "External links INSPIRE records for the paper."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"paper_not_found",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `paper_not_found`: The recid, arXiv ID, or DOI matches no INSPIRE literature record. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, was HTML where JSON was expected, or was invalid JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"recid": {
"type": "string",
"description": "INSPIRE literature record ID."
},
"shown": {
"type": "number",
"description": "Number of contributors listed."
},
"title": {
"type": "string",
"description": "Title as text: publisher HTML, JATS, and MathML converted (scripts as _x or ^{xy}), LaTeX left as published."
},
"notice": {
"type": "string",
"description": "Guidance when the recid asked for was merged into this record, the contributor list was capped, HEPData availability could not be checked, or the paper has more than one HEPData record."
},
"arxivId": {
"type": "string",
"description": "arXiv identifier, when the paper has one."
},
"authors": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"affiliations"
],
"properties": {
"bai": {
"type": "string",
"description": "INSPIRE BAI (e.g. Edward.Witten.1), when known; pass as author to cern_inspire_get_citation_summary."
},
"name": {
"type": "string",
"description": "Contributor name, \"Surname, Given names\"."
},
"orcid": {
"type": "string",
"description": "ORCID, when known."
},
"recid": {
"type": "string",
"description": "INSPIRE author record ID, when linked; pass as query to cern_inspire_search_authors for the profile."
},
"roles": {
"type": "array",
"items": {
"type": "string",
"description": "Recorded INSPIRE contributor role."
},
"description": "Roles in recorded order; absent roles are unknown."
},
"affiliations": {
"type": "array",
"items": {
"type": "string",
"description": "Affiliation name."
},
"description": "Affiliations listed for this contributor on this paper."
}
},
"description": "One contributor.",
"additionalProperties": false
},
"description": "Contributors in record order from authorOffset, capped at the effective max_authors budget."
},
"hepdata": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"enum": [
"available",
"none",
"lookup_failed"
],
"type": "string",
"description": "available: HEPData holds tables; none: it does not; lookup_failed: could not check."
},
"recordDoi": {
"type": "string",
"description": "HEPData record DOI; cite it when reusing the data."
},
"hepdataUrl": {
"type": "string",
"description": "The HEPData record page on hepdata.net, where the table values are read: keyed by the record number in recordDoi, or by this paper's recid (/record/ins followed by the recid) when recordDoi names no number."
},
"tableCount": {
"type": "number",
"description": "Number of tables in the latest version."
},
"otherRecords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recordDoi": {
"type": "string",
"description": "HEPData record DOI; cite it when reusing the data."
},
"hepdataUrl": {
"type": "string",
"description": "The HEPData record page on hepdata.net, where the table values are read: keyed by the record number in recordDoi, or by this paper's recid (/record/ins followed by the recid) when recordDoi names no number."
},
"tableCount": {
"type": "number",
"description": "Number of tables in the latest version."
},
"latestVersion": {
"type": "number",
"description": "Latest HEPData record version."
},
"inspireDataRecid": {
"type": "string",
"description": "Record ID of the HEPData entry in INSPIRE's data collection."
}
},
"description": "Another HEPData record of this paper.",
"additionalProperties": false
},
"description": "The paper's other HEPData records, in ascending record number, when it has more than one (at most 9 listed); the fields above describe the lowest-numbered record among the up to 10 the lookup returns."
},
"latestVersion": {
"type": "number",
"description": "Latest HEPData record version."
},
"inspireDataRecid": {
"type": "string",
"description": "Record ID of the HEPData entry in INSPIRE's data collection."
}
},
"description": "HEPData availability for the paper's numerical tables.",
"additionalProperties": false
},
"texkeys": {
"type": "array",
"items": {
"type": "string",
"description": "A texkey."
},
"description": "INSPIRE texkeys (BibTeX citation keys), current first."
},
"abstract": {
"type": "string",
"description": "Full abstract as text (arXiv-sourced when available): publisher markup converted like title, LaTeX left as published."
},
"citeable": {
"type": "boolean",
"description": "INSPIRE citeable flag, when recorded."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"description": "A keyword."
},
"description": "Keywords, de-duplicated."
},
"licenses": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "Licence URL."
},
"imposing": {
"type": "string",
"description": "Who imposes the licence, when recorded."
},
"material": {
"type": "string",
"description": "Which version of the paper the licence covers (e.g. preprint, publication), when recorded."
}
},
"description": "One licence.",
"additionalProperties": false
},
"description": "Licences recorded for the paper."
},
"refereed": {
"type": "boolean",
"description": "True when published in a refereed venue, when recorded."
},
"subjects": {
"type": "array",
"items": {
"type": "string",
"description": "INSPIRE subject."
},
"description": "INSPIRE subject categories."
},
"documents": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "Public attached-document URL."
},
"filename": {
"type": "string",
"description": "Recorded filename."
},
"fulltext": {
"type": "boolean",
"description": "Recorded full-text flag; absent means unknown."
},
"material": {
"type": "string",
"description": "Recorded version or material qualifier."
},
"description": {
"type": "string",
"description": "Recorded document description."
}
},
"description": "One public attached document.",
"additionalProperties": false
},
"description": "Public attached-document links in record order; no file contents are fetched."
},
"truncated": {
"type": "boolean",
"description": "True when available contributors remain after this page, including a zero-budget page."
},
"inspireUrl": {
"type": "string",
"description": "The paper on inspirehep.net."
},
"mergedFrom": {
"type": "string",
"description": "The recid asked for, when INSPIRE had merged that record into this one and redirects it here; cite and query this record by recid."
},
"resolvedAs": {
"enum": [
"recid",
"arxiv",
"doi"
],
"type": "string",
"description": "Which identifier form the paper input was resolved from."
},
"authorCount": {
"type": "number",
"description": "Upstream contributor count, falling back to the available contributor list length."
},
"citingQuery": {
"type": "string",
"description": "Literature query for papers citing this one; pass to cern_inspire_search_literature."
},
"experiments": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Experiment legacy name (e.g. CERN-LHC-ATLAS)."
},
"recid": {
"type": "string",
"description": "INSPIRE experiment record ID, when linked; pass as query to cern_inspire_search_experiments for the experiment record."
}
},
"description": "One linked experiment.",
"additionalProperties": false
},
"description": "Accelerator experiments linked to the paper."
},
"authorOffset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based starting position in the normalized available contributor list."
},
"preprintDate": {
"type": "string",
"description": "Preprint date, when recorded."
},
"publications": {
"type": "array",
"items": {
"type": "object",
"properties": {
"year": {
"type": "number",
"description": "Publication year."
},
"pages": {
"type": "string",
"description": "Page range or start page."
},
"volume": {
"type": "string",
"description": "Journal volume."
},
"journal": {
"type": "string",
"description": "Journal title (abbreviated)."
},
"freetext": {
"type": "string",
"description": "Free-text publication reference."
},
"articleId": {
"type": "string",
"description": "Article ID, for journals that number articles."
}
},
"description": "One publication reference.",
"additionalProperties": false
},
"description": "Publication references (journal, volume, year, pages)."
},
"citationCount": {
"type": "number",
"description": "Citations INSPIRE counts for the paper."
},
"documentTypes": {
"type": "array",
"items": {
"type": "string",
"description": "INSPIRE document type."
},
"description": "INSPIRE document types."
},
"numberOfPages": {
"type": "number",
"description": "Page count, when recorded."
},
"reportNumbers": {
"type": "array",
"items": {
"type": "string",
"description": "A report number."
},
"description": "Report numbers."
},
"abstractSource": {
"type": "string",
"description": "Who supplied the abstract (e.g. arXiv, a publisher)."
},
"collaborations": {
"type": "array",
"items": {
"type": "string",
"description": "Collaboration name."
},
"description": "Collaborations credited on the paper; empty for most non-collaboration papers."
},
"alternateTitles": {
"type": "array",
"items": {
"type": "string",
"description": "An alternate title."
},
"description": "Other titles INSPIRE records (translations, preprint titles), converted to text like title."
},
"arxivCategories": {
"type": "array",
"items": {
"type": "string",
"description": "arXiv category."
},
"description": "arXiv categories of the e-print."
},
"publicationDate": {
"type": "string",
"description": "Publication (imprint) date, when recorded."
},
"referencesQuery": {
"type": "string",
"description": "Literature query for this paper's references; pass to cern_inspire_search_literature."
},
"nextAuthorOffset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Pass as author_offset to read the next page; absent when no contributors remain or the budget is zero."
},
"citationCountWithoutSelf": {
"type": "number",
"description": "Citations excluding self-citations, when INSPIRE reports it."
}
},
"additionalProperties": false
}cern_inspire_get_paper annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_export_citations — Export INSPIRE citations
Advertised read-onlyOpen-world
Export INSPIRE-HEP's citation entries for the papers a literature query selects, as BibTeX or LaTeX \bibitem entries (EU or US style), keyed by INSPIRE texkeys and ready to paste into a bibliography. Name specific papers with "recid:451647 or arxiv:1207.7214 or doi:10.1016/…", or export a topic, author, or citing set with any query cern_inspire_search_literature accepts. Up to 50 entries per page; page through larger sets (only the first 10,000 matches are reachable). Entries are INSPIRE's verbatim text (long author lists arrive abbreviated as "First, Name and others").
cern_inspire_export_citations input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number, starting at 1. page × effective size (after clamping) may not exceed 10,000."
},
"size": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Entries per page (positive integer, default 10; above 50 uses 50)."
},
"sort": {
"enum": [
"relevance",
"mostrecent",
"mostcited"
],
"type": "string",
"default": "relevance",
"description": "Entry order: relevance (default), mostrecent, or mostcited."
},
"query": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "Literature query selecting the papers to cite, narrowed by the same document_types, subjects, year_from and year_to filters as search. Named papers: \"recid:451647 or arxiv:1207.7214 or doi:10.1016/j.physletb.2012.08.020\". Or a topic (\"t higgs and topcite 500+\"), an author (\"a Edward.Witten.1\"), or citing papers (\"refersto:recid:451647\"). Empty recognized field clauses such as a: or a:\"\" (including whitespace-only quoted values) are invalid; other syntax is passed through without complete grammar validation. See cern_inspire_list_reference topic search_syntax."
},
"format": {
"enum": [
"bibtex",
"latex-eu",
"latex-us"
],
"type": "string",
"default": "bibtex",
"description": "Entry format: bibtex (default), latex-eu, or latex-us (\\bibitem entries in European or US style)."
},
"year_to": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Latest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no upper bound."
},
"subjects": {
"type": "array",
"items": {
"enum": [
"Astrophysics",
"Phenomenology-HEP",
"Theory-HEP",
"Quantum Physics",
"Unknown",
"Gravitation and Cosmology",
"Experiment-HEP",
"Theory-Nucl",
"Accelerators",
"Instrumentation",
"General Physics",
"Experiment-Nucl",
"Math and Math Physics",
"Condensed Matter",
"Computing",
"Lattice",
"Other",
"Data Analysis and Statistics"
],
"type": "string",
"description": "An INSPIRE subject category."
},
"maxItems": 4,
"description": "Restrict to INSPIRE subject categories (up to 4). Multiple values must ALL hold, not either. Values: Astrophysics, Phenomenology-HEP, Theory-HEP, Quantum Physics, Unknown, Gravitation and Cosmology, Experiment-HEP, Theory-Nucl, Accelerators, Instrumentation, General Physics, Experiment-Nucl, Math and Math Physics, Condensed Matter, Computing, Lattice, Other, Data Analysis and Statistics."
},
"year_from": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Earliest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no lower bound."
},
"document_types": {
"type": "array",
"items": {
"enum": [
"article",
"published",
"conference paper",
"thesis",
"review",
"note",
"proceedings",
"lectures",
"book chapter",
"book",
"introductory",
"activity report",
"report"
],
"type": "string",
"description": "An INSPIRE document type."
},
"maxItems": 4,
"description": "Restrict to INSPIRE document types (up to 4). Multiple values must ALL hold (published + review = published reviews), not either. Values: article, published, conference paper, thesis, review, note, proceedings, lectures, book chapter, book, introductory, activity report, report."
}
},
"additionalProperties": false
}cern_inspire_export_citations output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"format",
"page",
"entries",
"appliedFilters",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The page size applied."
},
"page": {
"type": "number",
"description": "The page returned."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_year_range",
"beyond_result_window",
"invalid_query",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_year_range`: year_from is later than year_to. `beyond_result_window`: page × effective size (after clamping) exceeds the 10,000 results INSPIRE serves for one query. `invalid_query`: A recognized field clause has no value, or INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, the citation page was JSON or HTML instead of citation text, or selection verification returned unreadable JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of entries on this page."
},
"format": {
"enum": [
"bibtex",
"latex-eu",
"latex-us"
],
"type": "string",
"description": "The entry format returned."
},
"notice": {
"type": "string",
"description": "Guidance when size was reduced, nothing matched, the page is past the last or came back empty inside the match count, or more papers follow."
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"texkey",
"text"
],
"properties": {
"text": {
"type": "string",
"description": "The entry, verbatim as INSPIRE serves it."
},
"texkey": {
"type": "string",
"description": "INSPIRE texkey (the \\cite key), e.g. Maldacena:1997re; empty when INSPIRE gives none."
}
},
"description": "One citation entry.",
"additionalProperties": false
},
"description": "Citation entries, in the requested order."
},
"nextPage": {
"type": "number",
"description": "The page number to request next, when more papers follow within the 10,000-result window."
},
"truncated": {
"type": "boolean",
"description": "True when more matched papers follow this page."
},
"appliedFilters": {
"type": "string",
"description": "Sort and filters applied, or \"none\"."
}
},
"additionalProperties": false
}cern_inspire_export_citations annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_search_authors — Search INSPIRE authors
Advertised read-onlyOpen-world
Find physicist profiles in INSPIRE-HEP by name, INSPIRE BAI, ORCID, INSPIRE ID, or author recid. Each profile carries its recid, BAI, ORCID, current and past positions, advisors, arXiv categories, links, awards, and a literatureQuery that selects the person's papers in cern_inspire_search_literature. A name returns ranked candidates (a bare surname can match tens of thousands of profiles, and a less-cited namesake can rank first), so confirm the person from positions and categories before passing a bai or recid to cern_inspire_get_citation_summary. An identifier matches exactly.
cern_inspire_search_authors input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"default": 5,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Profiles to return (positive integer, default 5; above 25 uses 25)."
},
"query": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "A physicist's name (\"Witten, Edward\" or \"Edward Witten\") or one identifier: INSPIRE BAI (Edward.Witten.1, exact and case-sensitive), ORCID (0000-0002-7752-6073 or an orcid.org URL), INSPIRE ID (INSPIRE-00136372), or author recid."
}
},
"additionalProperties": false
}cern_inspire_search_authors output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"authors",
"totalCount",
"truncated",
"shown",
"cap",
"matchedAs"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_query",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_query`: INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, was HTML where JSON was expected, or was invalid JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of profiles returned."
},
"notice": {
"type": "string",
"description": "Guidance on an empty or capped result."
},
"authors": {
"type": "array",
"items": {
"type": "object",
"required": [
"recid",
"name",
"otherIds",
"currentPositions",
"pastPositions",
"arxivCategories",
"advisors",
"urls",
"awards",
"literatureQuery"
],
"properties": {
"bai": {
"type": "string",
"description": "INSPIRE BAI (exact, case-sensitive); use in literature queries as \"a <BAI>\" or pass as author to cern_inspire_get_citation_summary."
},
"name": {
"type": "string",
"description": "Name as INSPIRE records it, \"Last, First\"."
},
"stub": {
"type": "boolean",
"description": "True when the profile is an unclaimed stub generated from paper metadata."
},
"urls": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "URL."
},
"description": {
"type": "string",
"description": "Label INSPIRE gives the URL, when any."
}
},
"description": "One web link.",
"additionalProperties": false
},
"description": "Web links on the profile."
},
"orcid": {
"type": "string",
"description": "ORCID iD, when the profile links one."
},
"recid": {
"type": "string",
"description": "INSPIRE author record ID; pass to cern_inspire_get_citation_summary."
},
"awards": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Award name."
},
"year": {
"type": "number",
"description": "Year awarded, when recorded."
}
},
"description": "One award.",
"additionalProperties": false
},
"description": "Awards INSPIRE records."
},
"status": {
"type": "string",
"description": "Career status INSPIRE records (e.g. active, retired)."
},
"advisors": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Advisor name."
},
"recid": {
"type": "string",
"description": "Advisor author record ID, when linked."
},
"degreeType": {
"type": "string",
"description": "Degree supervised (e.g. phd, master), when recorded."
}
},
"description": "One advisor.",
"additionalProperties": false
},
"description": "Advisors INSPIRE records."
},
"otherIds": {
"type": "array",
"items": {
"type": "object",
"required": [
"schema",
"value"
],
"properties": {
"value": {
"type": "string",
"description": "Identifier value in that scheme."
},
"schema": {
"type": "string",
"description": "Identifier scheme (e.g. WIKIPEDIA, TWITTER, SPIRES)."
}
},
"description": "One further identifier.",
"additionalProperties": false
},
"description": "Identifiers beyond BAI, ORCID, and INSPIRE ID."
},
"inspireId": {
"type": "string",
"description": "INSPIRE ID (INSPIRE- plus 8 digits), when recorded."
},
"pastPositions": {
"type": "array",
"items": {
"type": "object",
"required": [
"institution"
],
"properties": {
"rank": {
"type": "string",
"description": "Rank or role (e.g. SENIOR, PHD, POSTDOC), when recorded."
},
"endDate": {
"type": "string",
"description": "End date (YYYY or YYYY-MM), when recorded."
},
"startDate": {
"type": "string",
"description": "Start date (YYYY or YYYY-MM), when recorded."
},
"institution": {
"type": "string",
"description": "Institution name as INSPIRE records it."
},
"institutionRecid": {
"type": "string",
"description": "INSPIRE institution record ID, when the position links one; pass affid:N, N being this ID, as the query of cern_inspire_search_literature or cern_inspire_get_citation_summary for the institution's papers."
}
},
"description": "One position held.",
"additionalProperties": false
},
"description": "Earlier positions."
},
"preferredName": {
"type": "string",
"description": "Preferred display name, when recorded."
},
"arxivCategories": {
"type": "array",
"items": {
"type": "string",
"description": "arXiv category."
},
"description": "arXiv categories the person publishes in."
},
"literatureQuery": {
"type": "string",
"description": "Literature query selecting this person's papers; pass to cern_inspire_search_literature."
},
"currentPositions": {
"type": "array",
"items": {
"type": "object",
"required": [
"institution"
],
"properties": {
"rank": {
"type": "string",
"description": "Rank or role (e.g. SENIOR, PHD, POSTDOC), when recorded."
},
"endDate": {
"type": "string",
"description": "End date (YYYY or YYYY-MM), when recorded."
},
"startDate": {
"type": "string",
"description": "Start date (YYYY or YYYY-MM), when recorded."
},
"institution": {
"type": "string",
"description": "Institution name as INSPIRE records it."
},
"institutionRecid": {
"type": "string",
"description": "INSPIRE institution record ID, when the position links one; pass affid:N, N being this ID, as the query of cern_inspire_search_literature or cern_inspire_get_citation_summary for the institution's papers."
}
},
"description": "One position held.",
"additionalProperties": false
},
"description": "Positions marked current."
}
},
"description": "One matching author profile.",
"additionalProperties": false
},
"description": "Matching profiles, in INSPIRE relevance order."
},
"matchedAs": {
"type": "string",
"description": "How the query was read: orcid, inspire_id, bai, or recid (exact identifier match), or name (free-text search)."
},
"truncated": {
"type": "boolean",
"description": "True when more profiles matched than were returned."
},
"totalCount": {
"type": "number",
"description": "Total author profiles the query matched."
}
},
"additionalProperties": false
}cern_inspire_search_authors annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_get_citation_summary — Get INSPIRE citation summary
Advertised read-onlyOpen-world
Compute INSPIRE-HEP's citation summary for one author or for any literature query: h-index, citation totals, average citations per paper, and paper counts per citation bucket (0, 1–9, 10–49, 50–99, 100–249, 250–499, 500+), each for all citeable papers and for published papers, plus citations received per year. Pass exactly one of author (a BAI, ORCID, INSPIRE ID, or author recid — resolve a name with cern_inspire_search_authors first) or query (any INSPIRE literature query: a topic, collaboration, institution, or "a <BAI>"). Document type and subject filters narrow every figure. year_from and year_to narrow the summary to papers from those years, and exclude_self_citations recounts it without self-citations; any of them leaves out citations per year, which INSPIRE cannot narrow that way.
cern_inspire_get_citation_summary input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"query": {
"type": "string",
"maxLength": 1000,
"description": "An INSPIRE literature query, e.g. \"collaboration:atlas\", \"t neutrino oscillation\", \"a Edward.Witten.1\", or \"affid:902725\" for an institution's papers (CERN; affid takes the institution recid that cern_inspire_search_authors and cern_inspire_search_experiments return). Empty recognized field clauses such as a: or a:\"\" (including whitespace-only quoted values) are invalid; other syntax is passed through without complete grammar validation. Literature queries do not match ORCIDs; pass an ORCID as author. Pass this or author, not both."
},
"author": {
"type": "string",
"maxLength": 200,
"description": "One author identifier: INSPIRE BAI (Edward.Witten.1, exact and case-sensitive), ORCID (0000-0002-7752-6073 or an orcid.org URL), INSPIRE ID (INSPIRE-00136372), or author recid. Not a name — resolve names with cern_inspire_search_authors first. Pass this or query, not both."
},
"year_to": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Latest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no upper bound."
},
"subjects": {
"type": "array",
"items": {
"enum": [
"Astrophysics",
"Phenomenology-HEP",
"Theory-HEP",
"Quantum Physics",
"Unknown",
"Gravitation and Cosmology",
"Experiment-HEP",
"Theory-Nucl",
"Accelerators",
"Instrumentation",
"General Physics",
"Experiment-Nucl",
"Math and Math Physics",
"Condensed Matter",
"Computing",
"Lattice",
"Other",
"Data Analysis and Statistics"
],
"type": "string",
"description": "An INSPIRE subject category."
},
"maxItems": 4,
"description": "Restrict to INSPIRE subject categories (up to 4). Multiple values must ALL hold, not either. Values: Astrophysics, Phenomenology-HEP, Theory-HEP, Quantum Physics, Unknown, Gravitation and Cosmology, Experiment-HEP, Theory-Nucl, Accelerators, Instrumentation, General Physics, Experiment-Nucl, Math and Math Physics, Condensed Matter, Computing, Lattice, Other, Data Analysis and Statistics."
},
"year_from": {
"type": "integer",
"maximum": 2100,
"minimum": 1900,
"description": "Earliest year to include (1900–2100, inclusive), matched on the earliest date INSPIRE records for the paper. Omit for no lower bound."
},
"document_types": {
"type": "array",
"items": {
"enum": [
"article",
"published",
"conference paper",
"thesis",
"review",
"note",
"proceedings",
"lectures",
"book chapter",
"book",
"introductory",
"activity report",
"report"
],
"type": "string",
"description": "An INSPIRE document type."
},
"maxItems": 4,
"description": "Restrict to INSPIRE document types (up to 4). Multiple values must ALL hold (published + review = published reviews), not either. Values: article, published, conference paper, thesis, review, note, proceedings, lectures, book chapter, book, introductory, activity report, report."
},
"exclude_self_citations": {
"type": "boolean",
"default": false,
"description": "Count citations without self-citations (INSPIRE's definition), default false. Setting it leaves out citationsByYear, which always includes self-citations."
}
},
"additionalProperties": false
}cern_inspire_get_citation_summary output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"target",
"matchedRecords",
"citeablePapers",
"hIndex",
"all",
"published",
"buckets",
"effectiveQuery",
"appliedFilters"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"all": {
"type": "object",
"required": [
"papers",
"citations"
],
"properties": {
"papers": {
"type": "number",
"description": "Number of citeable papers."
},
"citations": {
"type": "number",
"description": "Citations to the citeable papers."
},
"averageCitations": {
"type": "number",
"description": "Mean citations per citeable paper; omitted when there are no papers."
}
},
"description": "Totals over citeable papers.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"missing_target",
"author_not_identifier",
"author_not_found",
"invalid_year_range",
"invalid_query",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `missing_target`: Neither or both of author and query were given. `author_not_identifier`: author is not a BAI, ORCID, INSPIRE ID, or recid — usually a name. `author_not_found`: The author identifier matches no INSPIRE profile. `invalid_year_range`: year_from is later than year_to. `invalid_query`: A recognized field clause has no value, or INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, was HTML where JSON was expected, or was invalid JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"hIndex": {
"type": "object",
"required": [
"all",
"published"
],
"properties": {
"all": {
"type": "number",
"description": "h-index over all citeable papers."
},
"published": {
"type": "number",
"description": "h-index over published papers."
}
},
"description": "h-index for all citeable and for published papers.",
"additionalProperties": false
},
"notice": {
"type": "string",
"description": "Guidance when no citeable paper matched, or when citations per year were left out or could not be read."
},
"target": {
"type": "object",
"required": [
"kind",
"query"
],
"properties": {
"kind": {
"enum": [
"author",
"query"
],
"type": "string",
"description": "author when an author identifier was resolved; query for a literature query."
},
"query": {
"type": "string",
"description": "The literature query summarized (\"authors.recid:N\" for an author target)."
},
"authorName": {
"type": "string",
"description": "Name on the resolved author profile (author target only)."
},
"authorRecid": {
"type": "string",
"description": "INSPIRE author record ID the identifier resolved to (author target only)."
}
},
"description": "What the summary covers.",
"additionalProperties": false
},
"buckets": {
"type": "object",
"required": [
"all",
"published"
],
"properties": {
"all": {
"type": "array",
"items": {
"type": "object",
"required": [
"range",
"papers"
],
"properties": {
"range": {
"enum": [
"0",
"1–9",
"10–49",
"50–99",
"100–249",
"250–499",
"500+"
],
"type": "string",
"description": "Citation-count range of the bucket."
},
"papers": {
"type": "number",
"description": "Papers whose citation count falls in the range."
}
},
"description": "One citation bucket.",
"additionalProperties": false
},
"description": "Papers per citation range, over citeable papers."
},
"published": {
"type": "array",
"items": {
"type": "object",
"required": [
"range",
"papers"
],
"properties": {
"range": {
"enum": [
"0",
"1–9",
"10–49",
"50–99",
"100–249",
"250–499",
"500+"
],
"type": "string",
"description": "Citation-count range of the bucket."
},
"papers": {
"type": "number",
"description": "Papers whose citation count falls in the range."
}
},
"description": "One citation bucket.",
"additionalProperties": false
},
"description": "Papers per citation range, over published papers."
}
},
"description": "Papers per citation range, for all citeable and for published papers.",
"additionalProperties": false
},
"published": {
"type": "object",
"required": [
"papers",
"citations"
],
"properties": {
"papers": {
"type": "number",
"description": "Number of published papers."
},
"citations": {
"type": "number",
"description": "Citations to the published papers."
},
"averageCitations": {
"type": "number",
"description": "Mean citations per published paper; omitted when there are no papers."
}
},
"description": "Totals over published papers.",
"additionalProperties": false
},
"appliedFilters": {
"type": "string",
"description": "Filters applied, e.g. \"document_types=published; years=2012–2015; exclude_self_citations=true\", or \"none\"."
},
"citeablePapers": {
"type": "number",
"description": "Citeable papers among the matched records."
},
"effectiveQuery": {
"type": "string",
"description": "The literature query sent to INSPIRE."
},
"matchedRecords": {
"type": "number",
"description": "Literature records the query matched, citeable or not."
},
"citationsByYear": {
"type": "array",
"items": {
"type": "object",
"required": [
"year",
"citations"
],
"properties": {
"year": {
"type": "number",
"description": "Year of the citing records' earliest date."
},
"citations": {
"type": "number",
"description": "Citations the matched records received from records of that year."
}
},
"description": "Citations received in one year.",
"additionalProperties": false
},
"description": "Citations per year in ascending order, each counted in the year of the citing record's earliest date, self-citations included, over every matched record (citeable or not), so the sum can exceed all.citations. A year without citations has no row, and the current year counts citations to date. Empty when nothing matched or no matched record is cited; omitted when year_from, year_to, or exclude_self_citations is set, when INSPIRE did not return the series, or when the query matches more than about 150,000 records, which INSPIRE cannot count in time, unless INSPIRE answers within about 2 s (a series it has cached)."
}
},
"additionalProperties": false
}cern_inspire_get_citation_summary annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_search_experiments — Search INSPIRE experiments
Advertised read-onlyOpen-world
Find experiments, collaborations, and facilities in INSPIRE-HEP (ATLAS, CMS, DUNE, Belle II, …) by name, accelerator, or INSPIRE legacy name (CERN-LHC-CMS); digits alone look up an experiment recid. Each record carries the accelerator, host institutions, collaboration and subgroups, classification, lifecycle dates (proposed, approved, started, completed, ongoing), INSPIRE's paper count, a description, and a literatureQuery to pass to cern_inspire_search_literature or cern_inspire_get_citation_summary for the experiment's papers.
cern_inspire_search_experiments input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"default": 5,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Experiments to return (positive integer, default 5; above 25 uses 25)."
},
"query": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Experiment, collaboration, accelerator, or facility name (ATLAS, LHCb, Tevatron), an INSPIRE legacy name (CERN-LHC-CMS), or an experiment recid (digits only)."
}
},
"additionalProperties": false
}cern_inspire_search_experiments output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"experiments",
"totalCount",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_query",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_query`: INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, was HTML where JSON was expected, or was invalid JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of records returned."
},
"notice": {
"type": "string",
"description": "Guidance on an empty or capped result."
},
"truncated": {
"type": "boolean",
"description": "True when more records matched than were returned."
},
"totalCount": {
"type": "number",
"description": "Total experiment records the query matched."
},
"experiments": {
"type": "array",
"items": {
"type": "object",
"required": [
"recid",
"legacyName",
"institutions",
"classification",
"projectTypes",
"urls",
"nameVariants"
],
"properties": {
"core": {
"type": "boolean",
"description": "True when INSPIRE marks the record as core HEP."
},
"name": {
"type": "string",
"description": "Experiment name (e.g. ATLAS), when recorded."
},
"urls": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "URL."
},
"description": {
"type": "string",
"description": "Label INSPIRE gives the URL, when any."
}
},
"description": "One web link.",
"additionalProperties": false
},
"description": "Web links."
},
"recid": {
"type": "string",
"description": "INSPIRE experiment record ID."
},
"ongoing": {
"type": "boolean",
"description": "True when INSPIRE marks the experiment as still running, false when it records a completion date; omitted when INSPIRE records neither, so the status is unknown."
},
"longName": {
"type": "string",
"description": "Full descriptive name, when recorded."
},
"shortName": {
"type": "string",
"description": "Short form of the name, when recorded."
},
"legacyName": {
"type": "string",
"description": "INSPIRE legacy name (e.g. CERN-LHC-ATLAS), the key literatureQuery uses."
},
"accelerator": {
"type": "string",
"description": "Accelerator the experiment runs at, when any."
},
"dateStarted": {
"type": "string",
"description": "Date started, when recorded."
},
"description": {
"type": "string",
"description": "Description as INSPIRE records it."
},
"dateApproved": {
"type": "string",
"description": "Date approved, when recorded."
},
"dateProposed": {
"type": "string",
"description": "Date proposed, when recorded."
},
"institutions": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Institution name."
},
"recid": {
"type": "string",
"description": "INSPIRE institution record ID, when linked; pass affid:N, N being this ID, as the query of cern_inspire_search_literature or cern_inspire_get_citation_summary for the institution's papers."
}
},
"description": "One host institution.",
"additionalProperties": false
},
"description": "Host institutions."
},
"nameVariants": {
"type": "array",
"items": {
"type": "string",
"description": "Alternative name."
},
"description": "Alternative names INSPIRE matches."
},
"projectTypes": {
"type": "array",
"items": {
"type": "string",
"description": "Project type."
},
"description": "Project types (e.g. experiment, collaboration, accelerator)."
},
"collaboration": {
"type": "object",
"required": [
"name",
"subgroups"
],
"properties": {
"name": {
"type": "string",
"description": "Collaboration name."
},
"subgroups": {
"type": "array",
"items": {
"type": "string",
"description": "Subgroup name."
},
"description": "Named subgroups of the collaboration."
}
},
"description": "The collaboration running the experiment, when recorded.",
"additionalProperties": false
},
"dateCompleted": {
"type": "string",
"description": "Date completed; omitted while ongoing or when unrecorded."
},
"classification": {
"type": "array",
"items": {
"type": "string",
"description": "Classification path, e.g. \"Collider Experiments|Hadrons|p p\"."
},
"description": "INSPIRE classification paths."
},
"numberOfPapers": {
"type": "number",
"description": "INSPIRE's stored paper count; it can trail the number of records literatureQuery matches."
},
"literatureQuery": {
"type": "string",
"description": "Literature query selecting this experiment's papers; pass to cern_inspire_search_literature, or as query to cern_inspire_get_citation_summary. Absent when the record has no legacy name, or the name holds a quote or backslash that cannot sit inside the query's quoted clause."
}
},
"description": "One matching experiment record.",
"additionalProperties": false
},
"description": "Matching experiment records, in INSPIRE relevance order."
}
},
"additionalProperties": false
}cern_inspire_search_experiments annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_search_hepdata — Search HEPData records
Advertised read-onlyOpen-world
Find HEPData measurement records by physics content — process, observable, energy, collaboration — when the paper is unknown, through INSPIRE-HEP's index of every HEPData submission. Each hit carries the paper recids (pass to cern_inspire_get_paper), collaborations, keywords (reactions such as "P P --> TOP TOPBAR X", observables, centre-of-mass energies), the HEPData record DOI (recordDoi, the citation for the data), latest version, table count, and hepdataUrl, the hepdata.net record page that holds the table values; this tool does not return the values themselves. Only the first 10,000 results of a query are reachable.
cern_inspire_search_hepdata input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Page number, starting at 1. page × effective size (after clamping) may not exceed 10,000."
},
"size": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Records per page (positive integer, default 10; above 50 uses 50)."
},
"sort": {
"enum": [
"relevance",
"mostrecent"
],
"type": "string",
"default": "relevance",
"description": "Result order: relevance (default) or mostrecent."
},
"query": {
"type": "string",
"maxLength": 1000,
"minLength": 1,
"description": "Free text or INSPIRE syntax over HEPData records, e.g. top pair differential cross section 13 TeV; collaborations.value:LHCb; keywords.value:\"Inclusive\"; or literature.control_number:<recid> for one paper's data. INSPIRE does not reject malformed syntax; see cern_inspire_list_reference topic search_syntax."
}
},
"additionalProperties": false
}cern_inspire_search_hepdata output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"records",
"page",
"size",
"hasMore",
"totalCount",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The page size applied."
},
"page": {
"type": "number",
"description": "The page returned."
},
"size": {
"type": "number",
"description": "The effective page size after clamping."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"beyond_result_window",
"invalid_query",
"inspire_rate_limited",
"pacer_shed",
"upstream_unreadable"
],
"description": "Machine-readable failure mode. Declared by this tool: `beyond_result_window`: page × effective size (after clamping) exceeds the 10,000 results INSPIRE serves for one query. `invalid_query`: INSPIRE answered 400 to a parameter value it refuses. `inspire_rate_limited`: INSPIRE returned 429 after the pacer and retries. `pacer_shed`: The server's outbound INSPIRE queue could not start the request within the call's remaining budget. `upstream_unreadable`: The INSPIRE body exceeded the byte ceiling, was HTML where JSON was expected, or was invalid JSON. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of records on this page."
},
"notice": {
"type": "string",
"description": "Guidance on an empty or paged result."
},
"hasMore": {
"type": "boolean",
"description": "True when INSPIRE has a further page of results."
},
"records": {
"type": "array",
"items": {
"type": "object",
"required": [
"inspireDataRecid",
"title",
"paperRecids",
"collaborations",
"experiments",
"keywords"
],
"properties": {
"title": {
"type": "string",
"description": "Title of the HEPData submission (usually the paper title) as text: publisher markup converted (scripts as _x or ^{xy}), LaTeX left as published."
},
"created": {
"type": "string",
"description": "Date INSPIRE created the data record."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"description": "Keyword as INSPIRE stores it, e.g. \"cmenergies: 13000.0-13000.0\"."
},
"description": "HEPData keywords: reactions, observables, phrases, centre-of-mass energies."
},
"recordDoi": {
"type": "string",
"description": "HEPData record DOI; cite it when reusing the data."
},
"hepdataUrl": {
"type": "string",
"description": "The HEPData record page on hepdata.net, where the table values are read: keyed by hepdataRecid, or by the first of paperRecids (/record/ins followed by that recid) when the record DOI names no number."
},
"tableCount": {
"type": "number",
"description": "Number of tables in the latest version."
},
"experiments": {
"type": "array",
"items": {
"type": "string",
"description": "INSPIRE experiment legacy name."
},
"description": "Experiments credited, by INSPIRE legacy name."
},
"paperRecids": {
"type": "array",
"items": {
"type": "string",
"description": "INSPIRE literature record ID."
},
"description": "Literature records the data belongs to; pass to cern_inspire_get_paper."
},
"hepdataRecid": {
"type": "string",
"description": "HEPData record number, parsed from the record DOI: the N in hepdata.net/record/N. It is not an INSPIRE recid; pass one of paperRecids to cern_inspire_get_paper."
},
"citationCount": {
"type": "number",
"description": "Citations INSPIRE counts for the data record."
},
"latestVersion": {
"type": "number",
"description": "Latest HEPData record version."
},
"collaborations": {
"type": "array",
"items": {
"type": "string",
"description": "Collaboration name."
},
"description": "Collaborations credited."
},
"abstractSnippet": {
"type": "string",
"description": "Start of the first abstract with text, as text (numeric character references and 13 common named entities such as < and & decoded, other named entities left as written; publisher markup converted; LaTeX left as published), up to 300 characters at a word boundary."
},
"inspireDataRecid": {
"type": "string",
"description": "Record ID of the HEPData entry in INSPIRE's data collection."
},
"abstractTruncated": {
"type": "boolean",
"description": "True when the abstract continues past the snippet."
}
},
"description": "One matching HEPData record.",
"additionalProperties": false
},
"description": "The HEPData records on this page, in the requested order."
},
"nextPage": {
"type": "number",
"description": "The page number to request next, when one exists within the 10,000-result window."
},
"truncated": {
"type": "boolean",
"description": "True when more results exist beyond this page."
},
"totalCount": {
"type": "number",
"description": "Total HEPData records the query matched."
}
},
"additionalProperties": false
}cern_inspire_search_hepdata annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}cern_inspire_list_reference — INSPIRE reference vocabulary
Advertised read-only
Decode the vocabulary the other cern_inspire tools take: INSPIRE search syntax (field operators, boolean logic, sort orders, the 10,000-result window, and how malformed queries behave), identifier forms (recid, arXiv, DOI, BAI, ORCID, INSPIRE ID, institution recid, texkey, HEPData DOIs), the document_types and subjects filter values, citation-summary buckets, and HEPData record versions and DOIs. Static content with no upstream call; use it to build a query or to recover from an empty or unexpectedly broad result.
cern_inspire_list_reference input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"topic"
],
"properties": {
"topic": {
"enum": [
"search_syntax",
"identifiers",
"document_types",
"subjects",
"citation_buckets",
"hepdata"
],
"type": "string",
"description": "Which vocabulary to decode: search_syntax (query operators and rules), identifiers (paper, author, experiment, institution, and HEPData identifier forms), document_types, subjects, citation_buckets (citation-summary ranges and terms), or hepdata (record versions, DOIs, and licence)."
}
},
"additionalProperties": false
}cern_inspire_list_reference output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"topic",
"entries"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"topic": {
"enum": [
"search_syntax",
"identifiers",
"document_types",
"subjects",
"citation_buckets",
"hepdata"
],
"type": "string",
"description": "The topic decoded."
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"term",
"meaning"
],
"properties": {
"term": {
"type": "string",
"description": "The operator, identifier form, value, or concept."
},
"example": {
"type": "string",
"description": "A working example, when one applies."
},
"meaning": {
"type": "string",
"description": "What it means and how the tools use it."
}
},
"description": "One vocabulary entry.",
"additionalProperties": false
},
"description": "The entries for the topic."
}
},
"additionalProperties": false
}cern_inspire_list_reference annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
cern-inspire-guide
Use cern_inspire_* tools for HEP literature research, author or institution citation analysis, citation-network exploration, bibliography assembly, and finding numerical-data publications. Resolve identities, verify query scope, and distinguish publication-year filters from citation-year series before drawing conclusions.
cern-inspire-guide URI
skill://cern-inspire-guide/SKILL.mdinspire_literature — INSPIRE literature record
One INSPIRE-HEP literature record by recid, as the cern_inspire_get_paper dossier in JSON: title, abstract, contributors with affiliations and recorded roles (first 25 at authorOffset 0; authorCount gives the total), public attached-document links, publication, identifiers, citation counts, linked experiments, texkeys, and HEPData availability. A recid INSPIRE has merged into another record serves the surviving record, with mergedFrom naming the recid in the URI. Use cern_inspire_get_paper with author_offset set to nextAuthorOffset for further contributor pages, or to look a paper up by arXiv ID or DOI.
inspire_literature URI template
inspire://literature/{recid}io.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 1 of 1 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 675 ms
- 95th percentile latency
- 675 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 675 ms · metadata changed · 8 tool(s), 1 resource(s), 2 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http cern-inspire-mcp-server-caseyjhand https://cern-inspire.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add cern-inspire-mcp-server-caseyjhand --url https://cern-inspire.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"cern-inspire-mcp-server-caseyjhand": {
"url": "https://cern-inspire.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"cern-inspire-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://cern-inspire.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"cern-inspire-mcp-server-caseyjhand": {
"type": "http",
"url": "https://cern-inspire.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http cern-inspire-mcp-server-caseyjhand https://cern-inspire.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://cern-inspire.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"cern-inspire-mcp-server-caseyjhand": {
"serverUrl": "https://cern-inspire.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like cern-inspire-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.