io.github.cyanheads/crossref-mcp-server

Official7 toolsLive

by cyanheads · TypeScript

Resolve DOIs, search ~155M scholarly works, and fetch references via the Crossref REST API.

@cyanheads/crossref-mcp-server is an MCP server that resolves DOIs, searches approximately 155M scholarly works, fetches references, and looks up publishers using the Crossref REST API. It supports access via STDIO or Streamable HTTP, with a documented total of 7 tools.

🛠️ Key Features

Resolve DOIs
Search ~155M scholarly works
Fetch references
Look up publishers (via Crossref REST API)
Operate over STDIO or Streamable HTTP
7 tools

🚀 Use Cases

DOI resolution for scholarly citations
Broad academic discovery across a large Crossref dataset
Reference retrieval for publication graphs
Publisher metadata lookup

⚡ Developer Benefits

Integrates Crossref scholarly metadata into MCP-based workflows
Uses Crossref REST API as the metadata source
Works with both STDIO and Streamable HTTP transports

⚠️ Limitations

Functionality is bound to what Crossref provides through its REST API

Topics

academic-searchbibliometricscitationcrossrefdoimcpmcp-servermodel-context-protocolresearchscholarly-metadatatypescriptcyanheadsbunai-agent

Captured live from the server via tools/list.

crossref_get_work

Resolves a DOI to its full Crossref metadata record: title, authors, affiliations, abstract (when deposited), journal or container, publication date, type, license, full-text links, and funder acknowledgements. The author list is paged: authorCount is the full deposited total, offset and limit select the page (25 authors by default), and when authors remain the response carries a nextOffset to pass back as offset — large-collaboration papers deposit thousands. Outgoing references are reported as a count in referencesCount; the reference entries themselves come from crossref_get_references. The isReferencedByCount field reports the total incoming citation count from Crossref; the citing works themselves are not available through Crossref — use OpenAlex for citation graphs.

Parameters3

doi	string	required	DOI in the format "10.NNNN/suffix", e.g. "10.1038/nature12373". A resolver-wrapped form — "https://doi.org/10.1038/nature12373", "https://dx.doi.org/…", "doi:10.1038/nature12373" — is accepted and unwrapped.
offset	integer	optional	Zero-based index of the first author to return. Pass the nextOffset value from the previous response to continue through a long author list. Only the author list is paged; every other field of the record is returned in full on every page.
limit	integer	optional	Maximum number of authors to return in one page (1–500, default 25). Ordinary records fit in a single page; large-collaboration papers in particle physics and genomics deposit thousands.

Raw schema

{
  "type": "object",
  "properties": {
    "doi": {
      "type": "string",
      "pattern": "^(?:https?:\\/\\/(?:dx\\.)?doi\\.org\\/|doi:)?10\\.\\d{4,9}\\/\\S+$",
      "description": "DOI in the format \"10.NNNN/suffix\", e.g. \"10.1038/nature12373\". A resolver-wrapped form — \"https://doi.org/10.1038/nature12373\", \"https://dx.doi.org/…\", \"doi:10.1038/nature12373\" — is accepted and unwrapped."
    },
    "offset": {
      "default": 0,
      "description": "Zero-based index of the first author to return. Pass the nextOffset value from the previous response to continue through a long author list. Only the author list is paged; every other field of the record is returned in full on every page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 25,
      "description": "Maximum number of authors to return in one page (1–500, default 25). Ordinary records fit in a single page; large-collaboration papers in particle physics and genomics deposit thousands.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "doi"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

crossref_get_references

Returns the outgoing reference list for a DOI — the works cited by this paper. Each reference includes the deposited citation string and, where Crossref has resolved it, a DOI you can look up with crossref_get_work. Results are paged: referenceCount is the full deposited total, and when more remain the response carries a nextOffset to pass back as offset. Reference list coverage varies by publisher; many older works and non-participating publishers have no indexed references. Incoming citations — the works that cite this paper — are not available through Crossref; use OpenAlex for that.

Parameters3

doi	string	required	DOI in the format "10.NNNN/suffix", e.g. "10.1038/nature12373". A resolver-wrapped form — "https://doi.org/10.1038/nature12373", "https://dx.doi.org/…", "doi:10.1038/nature12373" — is accepted and unwrapped.
offset	integer	optional	Zero-based index of the first reference to return. Pass the nextOffset value from the previous response to continue through a long reference list.
limit	integer	optional	Maximum number of references to return in one page (1–500, default 100). Most works fit in a single page; bibliography records can carry tens of thousands.

Raw schema

{
  "type": "object",
  "properties": {
    "doi": {
      "type": "string",
      "pattern": "^(?:https?:\\/\\/(?:dx\\.)?doi\\.org\\/|doi:)?10\\.\\d{4,9}\\/\\S+$",
      "description": "DOI in the format \"10.NNNN/suffix\", e.g. \"10.1038/nature12373\". A resolver-wrapped form — \"https://doi.org/10.1038/nature12373\", \"https://dx.doi.org/…\", \"doi:10.1038/nature12373\" — is accepted and unwrapped."
    },
    "offset": {
      "default": 0,
      "description": "Zero-based index of the first reference to return. Pass the nextOffset value from the previous response to continue through a long reference list.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of references to return in one page (1–500, default 100). Most works fit in a single page; bibliography records can carry tens of thousands.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "doi"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

crossref_search_works

Searches the Crossref works index (~155M records) by free text and/or structured filters. The generic query matches loosely across all fields; scope precisely with the field-specific parameters queryTitle, queryAuthor, and queryContainerTitle, or resolve a known citation to its DOI with queryBibliographic — all combine with each other and with query. Use the filter parameter for structured filtering (object with hyphen-separated Crossref keys). Sort options: relevance, score, is-referenced-by-count, published, deposited, indexed. Each work returns at most authorLimit authors (25 by default) with authorCount reporting the full deposited total, since a single page of large-collaboration papers can carry tens of thousands of author entries; crossref_get_work pages the whole author list for any DOI whose list was cut. Offset-based paging is capped at ~10K results; use cursor="*" to start cursor-based deep paging, then pass the nextCursor value from each response to continue. The walk ends on the page where nextCursor is absent — that page also carries a notice saying the list is exhausted. Cursor and offset cannot be combined.

Parameters13

query	string	optional	Free-text search query, e.g. "CRISPR gene editing" or "climate change adaptation"
queryBibliographic	string	optional	Whole-citation match to resolve a known reference to its DOI. Combine title, author, year, and container into one string, e.g. "Watson Crick molecular structure of nucleic acids Nature 1953".
queryTitle	string	optional	Match against work titles only, e.g. "Array programming with NumPy".
queryAuthor	string	optional	Match against author names only, e.g. "Charles R. Harris".
queryContainerTitle	string	optional	Match against the container title (journal or book name) only, e.g. "Nature".
filter	object	optional	Structured filter object using Crossref hyphen-separated keys. All values must be strings. Boolean flag keys (has-abstract, has-references, has-full-text) require string values "true" or "false". Example: {"type":"journal-article","has-abstract":"true","from-pub-date":"2023-01-01","directory":"DOAJ"}
fields	array	optional	Fields to return (reduces payload). Names are case-sensitive. Useful set: DOI, title, author, published, type, is-referenced-by-count, abstract, container-title, publisher, score. DOI is always returned whether or not it is listed here, so every result stays resolvable by crossref_get_work.
rows	number	optional	Number of results to return per page (1–100, default 20)
authorLimit	integer	optional	Maximum number of authors to return per work (1–500, default 25). Ordinary records fit under the default; large-collaboration papers deposit thousands, and a page of them is large enough to exhaust a client context. Each work reports its full deposited total as authorCount — call crossref_get_work with that work doi to page the authors this cap left out.
offset	number	optional	Zero-based result offset for offset-based paging. Cannot be used with cursor. Capped at ~10K; use cursor for deeper paging.
cursor	string	optional	Cursor token for deep paging. Pass "*" to start cursor-based paging (required past ~10K results), then pass the nextCursor value from each response until a response omits it, which means the list is exhausted. Cannot be combined with offset.
sort	string	optional	Sort field
order	string	optional	Sort direction (asc or desc)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text search query, e.g. \"CRISPR gene editing\" or \"climate change adaptation\"",
      "type": "string"
    },
    "queryBibliographic": {
      "description": "Whole-citation match to resolve a known reference to its DOI. Combine title, author, year, and container into one string, e.g. \"Watson Crick molecular structure of nucleic acids Nature 1953\".",
      "type": "string"
    },
    "queryTitle": {
      "description": "Match against work titles only, e.g. \"Array programming with NumPy\".",
      "type": "string"
    },
    "queryAuthor": {
      "description": "Match against author names only, e.g. \"Charles R. Harris\".",
      "type": "string"
    },
    "queryContainerTitle": {
      "description": "Match against the container title (journal or book name) only, e.g. \"Nature\".",
      "type": "string"
    },
    "filter": {
      "description": "Structured filter object using Crossref hyphen-separated keys. All values must be strings. Boolean flag keys (has-abstract, has-references, has-full-text) require string values \"true\" or \"false\". Example: {\"type\":\"journal-article\",\"has-abstract\":\"true\",\"from-pub-date\":\"2023-01-01\",\"directory\":\"DOAJ\"}",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "fields": {
      "description": "Fields to return (reduces payload). Names are case-sensitive. Useful set: DOI, title, author, published, type, is-referenced-by-count, abstract, container-title, publisher, score. DOI is always returned whether or not it is listed here, so every result stays resolvable by crossref_get_work.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "rows": {
      "default": 20,
      "description": "Number of results to return per page (1–100, default 20)",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "authorLimit": {
      "default": 25,
      "description": "Maximum number of authors to return per work (1–500, default 25). Ordinary records fit under the default; large-collaboration papers deposit thousands, and a page of them is large enough to exhaust a client context. Each work reports its full deposited total as authorCount — call crossref_get_work with that work doi to page the authors this cap left out.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "description": "Zero-based result offset for offset-based paging. Cannot be used with cursor. Capped at ~10K; use cursor for deeper paging.",
      "type": "number",
      "minimum": 0
    },
    "cursor": {
      "description": "Cursor token for deep paging. Pass \"*\" to start cursor-based paging (required past ~10K results), then pass the nextCursor value from each response until a response omits it, which means the list is exhausted. Cannot be combined with offset.",
      "type": "string"
    },
    "sort": {
      "description": "Sort field",
      "type": "string",
      "enum": [
        "relevance",
        "score",
        "is-referenced-by-count",
        "published",
        "published-print",
        "published-online",
        "deposited",
        "indexed",
        "created",
        "updated",
        "references-count"
      ]
    },
    "order": {
      "description": "Sort direction (asc or desc)",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

crossref_search_journals

Finds Crossref journal records by ISSN or title query. Provide issn for an exact single-journal lookup, or query for title-based search returning up to rows results. Title-query results page with offset — the nextOffset enrichment carries the value for the following page, up to offset + rows = 100000. Set include_works to true to also return a page of the matched journal's most recent works by publication date; that list pages two ways. works_offset is the simple one and is capped ten times lower at works_offset + rows = 10000. works_cursor has no ceiling and reaches the whole works list: pass works_cursor="*" on the first call, then chain the nextWorksCursor token from each response. The two cannot be combined, and a cursor walk always starts at the newest work — it cannot resume from an offset. Returns journal metadata: title, publisher, ISSN-L, subject areas, and total DOI count.

Parameters7

query	string	optional	Journal title search query, e.g. "Nature" or "Journal of Machine Learning Research"
issn	string	optional	ISSN for exact single-journal lookup (print or electronic, with or without hyphen). Example: "1234-5678".
include_works	boolean	optional	When true, also return a page of the journal's most recent works by publication date. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN registered has no addressable works list; the works lookup is then skipped and the notice enrichment says so.
rows	number	optional	Maximum number of journals to return for title queries, or works when include_works is true (1–100, default 10)
offset	integer	optional	Zero-based offset into the title-query journal list. Pass the nextOffset value from the previous response to continue. Ignored when issn is set, which resolves exactly one record.
works_offset	integer	optional	Zero-based offset into the journal works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cursor to read the whole list. Cannot be combined with works_cursor.
works_cursor	string	optional	Cursor token for deep paging of the journal works list when include_works is true. Pass "*" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offset ceiling and cannot be combined with works_offset. Each token runs about 1500 characters and is returned on both result surfaces, a fixed cost per page — raise rows to spread it across more works on a long walk.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Journal title search query, e.g. \"Nature\" or \"Journal of Machine Learning Research\"",
      "type": "string"
    },
    "issn": {
      "description": "ISSN for exact single-journal lookup (print or electronic, with or without hyphen). Example: \"1234-5678\".",
      "type": "string",
      "pattern": "^\\d{4}-?\\d{3}[\\dX]$"
    },
    "include_works": {
      "default": false,
      "description": "When true, also return a page of the journal's most recent works by publication date. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN registered has no addressable works list; the works lookup is then skipped and the notice enrichment says so.",
      "type": "boolean"
    },
    "rows": {
      "default": 10,
      "description": "Maximum number of journals to return for title queries, or works when include_works is true (1–100, default 10)",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset into the title-query journal list. Pass the nextOffset value from the previous response to continue. Ignored when issn is set, which resolves exactly one record.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "works_offset": {
      "default": 0,
      "description": "Zero-based offset into the journal works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cursor to read the whole list. Cannot be combined with works_cursor.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "works_cursor": {
      "description": "Cursor token for deep paging of the journal works list when include_works is true. Pass \"*\" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offset ceiling and cannot be combined with works_offset. Each token runs about 1500 characters and is returned on both result surfaces, a fixed cost per page — raise rows to spread it across more works on a long walk.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

crossref_search_funders

Finds funders registered in the Crossref Funder Registry by name or funder DOI. Provide funder_doi for an exact single-funder lookup — the full DOI ("10.13039/100000001"), the bare registry ID ("100000001"), or either behind a doi: or https://doi.org/ prefix — or query for name-based search. Name-query results page with offset — the nextOffset enrichment carries the value for the following page, up to offset + rows = 100000. Set include_works to true to also return a page of works funded by the matched funder; that list pages two ways. works_offset is the simple one and is capped ten times lower at works_offset + rows = 10000. works_cursor has no ceiling and reaches the whole funded-works list: pass works_cursor="*" on the first call, then chain the nextWorksCursor token from each response. The two cannot be combined, and a cursor walk always starts at the newest work — it cannot resume from an offset. This list also counts works funded by the funder's registry descendants, which a crossref_search_works filter on {"funder": "10.13039/<id>"} does not. Returns funder name, registry ID, country, and alternate names. The Funder Registry supersedes entries, and a deprecated one answers to the same names as its successor while carrying only a fraction of its works: such a record carries replacedBy with the superseding registry ID and the response carries a notice naming it. The replacement is never followed automatically — re-run with funder_doi set to that ID to get the current entry.

Parameters7

query	string	optional	Funder name search query, e.g. "National Science Foundation" or "Wellcome Trust"
funder_doi	string	optional	Funder DOI for exact lookup — the full DOI "10.13039/100000001" (NSF) or the bare registry ID "100000001". Supersedes query when provided.
include_works	boolean	optional	When true, also return a page of works funded by the matched funder. Requires an unambiguous funder — pass funder_doi when a name query matches more than one.
rows	number	optional	Maximum funders to return for name queries, or works when include_works is true (1–100, default 10)
offset	integer	optional	Zero-based offset into the name-query funder list. Pass the nextOffset value from the previous response to continue. Ignored when funder_doi is set, which resolves exactly one record.
works_offset	integer	optional	Zero-based offset into the funded-works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cursor to read the whole list. Cannot be combined with works_cursor.
works_cursor	string	optional	Cursor token for deep paging of the funded-works list when include_works is true. Pass "*" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offset ceiling and cannot be combined with works_offset. Each token runs about 1500 characters and is returned on both result surfaces, a fixed cost per page — raise rows to spread it across more works on a long walk.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Funder name search query, e.g. \"National Science Foundation\" or \"Wellcome Trust\"",
      "type": "string"
    },
    "funder_doi": {
      "description": "Funder DOI for exact lookup — the full DOI \"10.13039/100000001\" (NSF) or the bare registry ID \"100000001\". Supersedes query when provided.",
      "type": "string",
      "pattern": "^(?:(?:https?:\\/\\/(?:dx\\.)?doi\\.org\\/|doi:)?10\\.13039\\/)?\\d+$"
    },
    "include_works": {
      "default": false,
      "description": "When true, also return a page of works funded by the matched funder. Requires an unambiguous funder — pass funder_doi when a name query matches more than one.",
      "type": "boolean"
    },
    "rows": {
      "default": 10,
      "description": "Maximum funders to return for name queries, or works when include_works is true (1–100, default 10)",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Zero-based offset into the name-query funder list. Pass the nextOffset value from the previous response to continue. Ignored when funder_doi is set, which resolves exactly one record.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "works_offset": {
      "default": 0,
      "description": "Zero-based offset into the funded-works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cursor to read the whole list. Cannot be combined with works_cursor.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "works_cursor": {
      "description": "Cursor token for deep paging of the funded-works list when include_works is true. Pass \"*\" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offset ceiling and cannot be combined with works_offset. Each token runs about 1500 characters and is returned on both result surfaces, a fixed cost per page — raise rows to spread it across more works on a long walk.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

crossref_get_member

Resolves a Crossref member ID to its publisher/organization record: primary name, alternate imprint names, owned DOI prefixes, registered DOI counts, a per-work-type breakdown, and per-category metadata deposit coverage. Members are the organizations that register DOIs with Crossref, so this answers "what does this publisher publish, and how completely do they deposit metadata?" Resolve a DOI prefix (e.g. "10.1038") to its member ID with crossref_get_prefix, then pass that ID here.

Parameters1

member_id

integer

required

Crossref member ID — a positive integer, e.g. 297 (Springer) or 340 (PLOS). Resolve a DOI prefix to a member ID first with crossref_get_prefix.

Raw schema

{
  "type": "object",
  "properties": {
    "member_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Crossref member ID — a positive integer, e.g. 297 (Springer) or 340 (PLOS). Resolve a DOI prefix to a member ID first with crossref_get_prefix."
    }
  },
  "required": [
    "member_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

crossref_get_prefix

Resolves a DOI prefix — the registrant portion of a DOI, e.g. "10.1038" — to its owning Crossref member: the publisher name and numeric member ID. Answers "who publishes DOIs starting with 10.1038?" The Crossref prefix record carries only these three facts (no counts, coverage, or flags); the returned memberId chains directly into crossref_get_member for the full publisher record.

Parameters1

prefix

string

required

DOI prefix in the format "10.NNNN" — the registrant portion of a DOI with no "/suffix", e.g. "10.1038" or "10.1371".

Raw schema

{
  "type": "object",
  "properties": {
    "prefix": {
      "type": "string",
      "pattern": "^10\\.\\d+$",
      "description": "DOI prefix in the format \"10.NNNN\" — the registrant portion of a DOI with no \"/suffix\", e.g. \"10.1038\" or \"10.1371\"."
    }
  },
  "required": [
    "prefix"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md20 KBView on GitHub

@cyanheads/crossref-mcp-server

Resolve DOIs, search ~155M scholarly works, fetch references, and look up publishers via the Crossref REST API. STDIO or Streamable HTTP.

7 Tools

Version MCP SDK TypeScript

Public Hosted Server: https://crossref.caseyjhand.com/mcp

Overview

Scholarly metadata from the Crossref REST API. Resolve DOIs to full metadata records, search across ~155 million scholarly works by free text or structured filters, fetch outgoing reference lists, and look up journals, funders, and publishers. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`crossref_get_work`	Resolve a DOI to its full Crossref metadata record: title, authors, editors, affiliations, abstract, journal with volume/issue/pages, ISSNs and ISBNs, publication date, license, full-text links, funder acknowledgements, post-publication updates, and related identifiers
`crossref_search_works`	Search the Crossref works index by free text and/or structured filters, with field-scoped query parameters, sort, field selection, and offset or cursor-based paging
`crossref_get_references`	Return the outgoing reference list for a DOI — the works cited by this paper, with citation strings and resolved DOIs where available
`crossref_search_journals`	Find Crossref journal records by ISSN or title query; optionally retrieve a page of the journal's most recent works
`crossref_search_funders`	Find funders in the Crossref Funder Registry by name, registry ID, or funder DOI; optionally retrieve a page of funded works
`crossref_get_member`	Resolve a Crossref member ID to its publisher record — name, owned DOI prefixes, DOI counts, and per-category metadata deposit coverage
`crossref_get_prefix`	Resolve a DOI prefix (e.g. `10.1038`) to its owning publisher, chaining into `crossref_get_member`

Capability reference

`crossref_get_work` _tool

DOI validated against the 10.NNNN/suffix regex before the upstream call, accepted either bare or wrapped in its resolver (https://doi.org/…, https://dx.doi.org/…, doi:…) and unwrapped before the lookup
Returns title, authors with affiliations, abstract (when deposited), container/journal, publication date, work type, ISSN, license URLs, full-text link URLs, and funder acknowledgements
Citation locators volume, issue, page, and articleNumber under the same names and on the same rendered line as crossref_search_works, plus isbn — each as deposited, omitted when absent
editors in the author entry shape, returned whole and never counted in authorCount
Author list paged by offset/limit (default 25, max 500); authorCount reports the full deposited total and a nextOffset continues when authors remain — every other field is returned in full on every page
updatedBy lists the corrections, retractions, expressions of concern, and new versions Crossref records against the work — notice DOI, type, source (publisher or retraction-watch, with its record ID), and date, entry for entry — and updateTo the works this record is a notice for; when updatedBy is present, notice names each update type with its sources. An absent updatedBy does not mean the work was never updated
relations groups related identifiers (preprint ↔ published version, versions, reviews, supplements) by relation type, identifier type, and asserting party, returned whole; only Crossref-registered DOIs among them resolve through this tool
A funder or affiliation asserted only through the ROR registry (no name deposited) carries ror in place of name, never as a blank entry
Publication date is the first of published, published-print, published-online, and issued (this tool only) that names a value; a date component Crossref records as unknown is omitted, along with everything less precise below it
Outgoing references are reported as a count (referencesCount) — entries come from crossref_get_references; incoming citation count (isReferencedByCount) is included, but citing works are not exposed by Crossref — use OpenAlex for citation graphs

`crossref_search_works` _tool

Free-text query plus a structured filter object using Crossref's hyphenated keys (from-pub-date, type, funder, issn, has-abstract, license.url, etc.)
Field-scoped parameters queryTitle, queryAuthor, queryContainerTitle, and queryBibliographic combine with query and with each other
Sort by relevance, score, is-referenced-by-count, published, deposited, or other listed fields — the publication-date sorts page by offset only, since Crossref refuses them with a cursor
fields narrows the payload to any of the 17 select names the summary projects — including the citation locators volume, issue, page, article-number, and ISSN — and refuses any other name; DOI is always returned, and crossref_get_work carries the rest of the record
A blank or whitespace-only query term or filter value, and an empty sort or order, is read as omitted; when that leaves nothing to search by, the notice says the page is an unfiltered listing
authorLimit caps authors per work (default 25, max 500); authorCount reports the full deposited total — chain a cut work's DOI into crossref_get_work for the rest
Offset paging is capped at ~10K; cursor="*" starts deep paging via chained nextCursor tokens — cursor and offset cannot be combined
A cursor walk ends on the page that omits nextCursor — an empty page never carries one; every empty page's notice names which of the three causes applies

`crossref_get_references` _tool

Takes the citing work's DOI bare or resolver-wrapped, the same forms crossref_get_work accepts
Each reference carries its deposited citation string and, when Crossref has resolved it, a DOI for crossref_get_work
Citation strings have formatting markup stripped and character references decoded; a bracketed span that isn't a recognized tag (a cited URL, a Miller index, a DOI fragment) is left exactly as deposited
Paged by offset/limit (default 100, max 500); referenceCount is the full deposited total and nextOffset continues when more remain
Coverage varies by publisher — pre-2000 works and non-participating publishers often have no indexed references
Single-hop only; incoming citations are not available through Crossref — use OpenAlex for citation graphs

`crossref_search_journals` _tool

include_works: true also returns a page of the journal's most recent works — newest published first by works_offset, newest registered first on a works_cursor walk; requires an unambiguous journal — a title query matching more than one returns ambiguous_journal, naming candidates and ISSNs
Returns journal title, publisher, ISSN-L, subject areas, and total DOI count
Title-query results page by offset (ceiling offset + rows ≤ 100,000); the works list pages separately by works_offset (ceiling ≤ 10,000) — a page that stalls at either ceiling, or an offset past the end of either list, carries a notice naming it
works_cursor="*" pages the works list with no ceiling via chained nextWorksCursor tokens; a cursor walk runs by Crossref registration date, newest first (Crossref does not walk a publication-date sort by cursor), and cannot combine with works_offset > 0 (works_cursor_offset_conflict)
A matched journal with no ISSN registered has no addressable works list — include_works is skipped with a notice rather than returning an empty list

`crossref_search_funders` _tool

Accepts a name query, a bare registry ID (100000001), or a full funder DOI (10.13039/100000001, optionally behind a doi:/https://doi.org/ prefix)
include_works: true also returns a page of funded works; requires an unambiguous funder — a name query matching more than one returns ambiguous_funder, naming candidates and registry IDs
Returns funder name, registry ID, country, and alternate names
Name-query results page by offset (ceiling ≤ 100,000); the funded-works list pages separately by works_offset (ceiling ≤ 10,000) or, with no ceiling, works_cursor="*" chaining nextWorksCursor — offset pages run newest published first, a cursor walk newest registered first, and the two cannot combine (works_offset > 0); an offset past the end of either list carries a notice naming it
The funded-works list also counts works funded by the funder's registry descendants, which a crossref_search_works filter on {"funder": "10.13039/<id>"} does not
A deprecated registry entry answers to its successor's name while counting only its own works — the response's notice names the superseding ID via replacedBy; the replacement is never followed automatically

`crossref_get_member` _tool

Members are the organizations that register DOIs — this answers "what does this publisher publish, and how completely do they deposit metadata?"
Returns primary name, alternate imprint names, owned DOI prefixes, DOI counts (total/current/backfile), a per-work-type breakdown, and per-category metadata deposit coverage (references, abstracts, ORCIDs, funders, licenses, and more) as current/backfile fractions
Pair with crossref_get_prefix to resolve a DOI prefix to the member ID first

`crossref_get_prefix` _tool

Accepts the registrant prefix of a DOI (e.g. 10.1038, no /suffix)
Returns the publisher name and numeric member ID — the ID chains directly into crossref_get_member for the full record
The Crossref prefix record is thin by design (owner name and member link only); richer publisher data lives on the member record

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.

Crossref-specific:

Polite-pool User-Agent header injected on every request — priority access via CROSSREF_MAILTO, keyless otherwise; no API token required
Retry with exponential backoff on 429 (honoring Retry-After), 5xx, HTTP 408/504, and network failures; a malformed response body and a request that hits CROSSREF_TIMEOUT_MS are not retried
Cursor-based deep paging on the works search and on both works sub-resources, for result sets beyond the offset cap
Crossref's rejections of a request come back as declared reasons — unknown_filter (with the hyphenated key when Crossref lists one), invalid_parameter, sort_cursor_conflict, invalid_cursor — carrying the rejected inputs and a recovery hint; a malformed issn filter value is refused before the request, and no upstream error relays Crossref's raw response body
Text normalization on every human-readable value: HTML character references decoded and whitespace collapsed; citation strings additionally have formatting markup stripped, so titles and abstracts read as plain text instead of raw JATS XML; a MathML formula keeps its structure — the TeX annotation where the deposit carries one, otherwise a linear form such as x_i, A^{−1}, √(m), (a+b)/c

Agent-friendly output:

Provenance — identifiers, URLs, and dates are returned byte-exact while human-readable text is normalized, so a caller can trust doi, issn, and date fields without re-verification
Graceful partial failure — an empty page is a success, not an error: an offset past the end of a list, or a query nothing matched, carries a notice saying which, and so does the page that ends a crossref_search_works cursor walk; a journal or funder works walk ends on the page that omits nextWorksCursor
Discriminated output contracts — the nextCursor, nextOffset, nextWorksOffset, and nextWorksCursor continuation fields are withheld once a list is exhausted, and a page that stops at an offset ceiling says so in its notice; a cursor token can still ride the last partial page, and the empty page after it carries none
Ambiguity handled explicitly — ambiguous_journal and ambiguous_funder list every candidate and its identifier in the error data rather than silently resolving to the first match

Getting started

Public Hosted Instance

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

json

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

Self-Hosted / Local

Add the following to your MCP client configuration file. CROSSREF_MAILTO is optional but recommended — without it the server uses Crossref's anonymous pool with stricter rate limits.

json

{
  "mcpServers": {
    "crossref-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/crossref-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "crossref-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/crossref-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "crossref-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "CROSSREF_MAILTO=your-email@example.com",
        "ghcr.io/cyanheads/crossref-mcp-server:latest"
      ]
    }
  }
}

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

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CROSSREF_MAILTO=your-email@example.com bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
An email address for CROSSREF_MAILTO is optional but recommended — Crossref's polite pool grants priority access to clients that identify themselves. No account or token is required.

Installation

Clone the repository:

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

Navigate into the directory:

cd crossref-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env and optionally set CROSSREF_MAILTO for polite-pool access

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

Variable	Description	Default
`CROSSREF_MAILTO`	Email address embedded in the polite-pool `User-Agent` header. Optional — server starts without it but logs a warning and uses the anonymous pool with stricter rate limits.	—
`CROSSREF_BASE_URL`	Crossref API base URL. Override for testing against a local proxy.	`https://api.crossref.org`
`CROSSREF_TIMEOUT_MS`	Per-request timeout in milliseconds. Also the worst-case wait against an unresponsive upstream — a request that hits the deadline is not retried.	`10000`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_SESSION_MODE`	HTTP session mode: `auto`, `stateful`, or `stateless`. This server needs no multi-round input, so `src/index.ts` declares `stateless`; Docker and `.env.example` pin the same value, and setting this variable overrides the declaration.	`stateless` (declared in `src/`)
`MCP_HTTP_PORT`	Port for the HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

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

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and inits services.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/services/crossref`	CrossrefService — HTTP client, polite-pool header, retry, pagination helpers.
`tests/`	Unit and integration tests mirroring `src/`.

Development guide

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

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields (abstracts, reference lists, and affiliations are frequently absent in Crossref records)

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (7)

crossref_get_workcrossref_get_referencescrossref_search_workscrossref_search_journalscrossref_search_funderscrossref_get_membercrossref_get_prefix

Configuration

Environment variables

CROSSREF_MAILTO

Email for polite-pool User-Agent header — optional. Without: anonymous pool with stricter rate limits.

CROSSREF_BASE_URLdefault https://api.crossref.org

Override the Crossref API base URL. Defaults to https://api.crossref.org.

CROSSREF_TIMEOUT_MSdefault 10000

Per-request timeout in milliseconds.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "crossref-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/crossref-mcp-server@0.4.1",
        "run",
        "start:stdio"
      ],
      "env": {
        "CROSSREF_MAILTO": "<YOUR_CROSSREF_MAILTO>",
        "CROSSREF_BASE_URL": "https://api.crossref.org",
        "CROSSREF_TIMEOUT_MS": "10000",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

crossref_get_work

crossref_get_references

crossref_search_works

crossref_search_journals

crossref_search_funders

crossref_get_member

crossref_get_prefix

@cyanheads/crossref-mcp-server

Overview

Tools

Capability reference

crossref_get_work tool

crossref_search_works tool

crossref_get_references tool

crossref_search_journals tool

crossref_search_funders tool

crossref_get_member tool

crossref_get_prefix tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`crossref_get_work` _tool

`crossref_search_works` _tool

`crossref_get_references` _tool

`crossref_search_journals` _tool

`crossref_search_funders` _tool

`crossref_get_member` _tool

`crossref_get_prefix` _tool