Overview

Scholarly metadata from the Crossref REST API. Resolve DOIs to full metadata records, search across ~188 million scholarly works by free text or structured filters, fetch outgoing reference lists, and look up journals, funders, and publishers.

Tools

Resources

The skill is also served through the skill://{+path} template and ships as skills/crossref-guide/SKILL.md in the npm package, the Docker image, the .mcpb bundle, and plugin installs. The tools do not depend on it.

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
• containerTitles lists every container title the record deposits, in deposited order — a book chapter or proceedings paper often deposits its series and then its book or volume — beside containerTitle, which keeps the first; crossref_search_works returns both, and its container-title select name fills both
• 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
• memberId is the Crossref member that holds the DOI now — pass it to crossref_get_member for the publisher record. For a title transferred to another publisher it differs from the member the DOI's prefix names through crossref_get_prefix
• editors in the author entry shape, returned whole and never counted in authorCount
• Author list paged by offset/limit (default 25, up to 10,000 per call — a larger limit is clamped to 10,000 with a notice); 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
• clinicalTrialNumbers (number, registry, type) lists the trial registrations the work names, and assertions the Crossmark entries its publisher attaches — article-history dates, ethics and competing-interest statements (told apart by groupLabel), peer-review details, boilerplate — each returned whole in deposited order, a repeated entry included, and omitted when not deposited. An assertion's value is normalized text, never parsed into a date; its url is omitted where it repeats value; Crossref's per-group order is not carried, since array order is the sequence. A missing clinicalTrialNumbers does not mean the work reports no trial
• event (name, acronym, location, start, end) is the conference a proceedings paper was presented at, and crossref_search_works returns it in the same shape; institutions (name, ror, place, department, acronym — the awarding institution of a thesis, the server a preprint was posted to, the laboratories behind a report), degree, subtype, and groupTitle are crossref_get_work only, since Crossref refuses institution and subtype as select names. Each is omitted when the record deposits none
• A funder, affiliation, or institution 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. approved is its own field — the only date most dissertations and standards deposit — and is never read into the publication date, which stays absent on a record that states none
• 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
• A DOI Crossref holds no record for returns doi_not_found naming the agency the DOI registry says holds it (registrationAgency — DataCite, JaLC, mEDRA, …), a Funder Registry pointer when Crossref registered it, or that no agency registered it at all. A DOI registered with DataCite, JaLC, mEDRA, KISTI, or OP also carries its citation (data.citation and the message): title, authors (the first 25, with authorCount), container title, issued date, publisher, and type, each where the agency has one

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.); dissertations and most standards deposit approved rather than a publication date, so bound them with from-approved-date / until-approved-date, which the pub-date filters do not read
• 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. A cursor walk with a query term and no sort runs by relevance (sent as sort=score, without order) and can repeat or skip a record at a page boundary; sort: "created" walks without repeats. A filter-only walk runs in Crossref registration order
• Crossref's own parameter names are accepted as input aliases: select for fields, and query.bibliographic, query.title, query.author, query.container-title for the four field-scoped parameters
• fields narrows the payload to any of the 22 select names the summary projects — including the citation locators volume, issue, page, article-number, and ISSN, the update links updated-by and update-to, approved, event, and member for memberId, which every work also carries when fields is omitted — and refuses any other name; DOI is always returned, and crossref_get_work carries the rest of the record
• Each work carries updatedBy (corrections, retractions, expressions of concern, new versions recorded against it) and updateTo (the works it is a notice for) in the entry shape and rendered line crossref_get_work uses, so a page of results can be screened for retractions without a call per DOI
• 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
• rows returns up to 500 works per call, or up to 1,000 when fields names neither abstract nor author, and authorLimit caps authors per work (default 25, up to 500); a larger value of either is clamped to its cap with a notice, which on an offset page also names the offset that continues after the records returned; authorCount reports the full deposited total — chain a cut work's DOI into crossref_get_work for the rest
• facets counts the matching works per value of any of Crossref's 21 facet names (published, publisher-name, type-name, funder-name, affiliation, orcid, update-type, …) in the same call, each set to "*" or a number of values — {"published": "*", "publisher-name": 10}. Counts cover every record totalResults counts, not only the page, and each value list is ordered by count, highest first. Crossref returns at most 1,000 values per facet, so a larger count is applied as 1,000 with a notice, and a facet whose values reach its limit is named there as one that may have more; Crossref's value-count counts the values returned, so no distinct total is reported. rows: 0 returns the counts and totalResults with no works, and leaves a cursor walk where it was
• Offset paging is capped at offset + rows ≤ 10,000: a page that would pass it returns the rows that fit, with a notice naming the rows requested and applied, and an offset of 10,000 or more is refused (offset_too_large); 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, except a rows: 0 page, which is empty by request and is told apart only when nothing matched

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, with doiAssertedBy saying whether the publisher deposited that DOI or Crossref matched it
• Structured parts as deposited: author, year, article title, journal title, the title of a cited book or volume (volumeTitle, which stands in as the title when there is no article title), series title, volume, issue, first page, edition, and ISSN
• 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, up to 4,000 per call — a larger limit is clamped to 4,000 with a notice); 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
• A DOI Crossref holds no record for returns doi_not_found naming its registration agency (registrationAgency), or saying no agency registered it, the same way crossref_get_work does; a DOI registered with DataCite, JaLC, mEDRA, KISTI, or OP carries its citation (data.citation and the message) as well

crossref_search_journals _tool

• include_works: true also returns a page of the journal's most recent works, drawn from every ISSN its record lists whichever one was passed — 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
• rows takes up to 1,000, for the title-query journal list and the include_works list alike
• Returns journal title, publisher, ISSNs with their print/electronic form, subject areas, DOI counts (total/current/backfile), and per-category metadata deposit coverage (abstracts, references, ORCIDs, funders, licenses, and more) as current/backfile fractions — the same breakdown crossref_get_member gives per publisher
• An issn lookup also returns DOI counts by issued year, ascending; title-query results omit them
• 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 would pass either ceiling returns the rows that fit, with a notice naming the rows requested and applied, and only an offset at or past a ceiling is refused; an offset past the end of either list carries a notice naming it, and so does a page that reaches either ceiling with records past 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 well-formed 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); a page that would pass either ceiling returns the rows that fit, with a notice naming the rows requested and applied, and only an offset at or past a ceiling is refused; an offset past the end of either list carries a notice naming it, and so does a page that reaches either ceiling with records past 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 funder_doi lookup returns those descendants' registry IDs as descendants, every depth, whole — OR'd with the funder's ID in the funder filter they count the same scope with date, type, or other filters. The lookup's worksCount is the Funder Registry record's own count, which can differ from the funder filter's total — a crossref_search_works call with rows: 0 returns the exact figure in totalResults
• 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
• A funder's replaces IDs are counted by neither the funded-works list nor the funder filter on its own ID: OR them in ({"funder": "<id>,funder:<replaced>,…"}) to count its whole history

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
• The member that holds a DOI now is the memberId crossref_get_work or crossref_search_works returns for it; crossref_get_prefix returns the member a prefix record names, which for a transferred title is a former publisher

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 prefix record names — the prefix's registrant — and the ID chains directly into crossref_get_member for the full record. A DOI under a title transferred to another publisher keeps its prefix, so its current member is the memberId crossref_get_work returns
• The Crossref prefix record is thin by design (owner name and member link only); richer publisher data lives on the member record
• A prefix with no Crossref member returns prefix_not_found naming the agency that registered it (registrationAgency, e.g. DataCite for 10.5281), or saying no agency registered it

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 Crossref 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 the journal and funder works lists, 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 structured abstract keeps its section headings apart from their text (Objectives: …), drops a leading "Abstract" heading and any heading whose section holds no text (a figure-only "Graphical Abstract"), joins the items of a list with ; where an item does not already end in punctuation, and is omitted when no text is left; 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, a page that reaches an offset ceiling says so in its notice, and one that would pass it is cut to the rows that fit; 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

Connect to the hosted instance, no install:

claude mcp add --transport http crossref-mcp-server https://crossref.caseyjhand.com/mcp

Or run it locally:

claude mcp add crossref-mcp-server -- npx -y @cyanheads/crossref-mcp-server

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

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

Setting CROSSREF_MAILTO to your email moves requests into Crossref's polite pool, which has higher rate limits than the anonymous pool; no account or token is needed. For Docker or a source build, see Running the server.

Configuration

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

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

Running the server

Local development

Requires Bun v1.4.4 or higher (or Node.js v24+).

• Clone and install:

  git clone https://github.com/cyanheads/crossref-mcp-server.git
  cd crossref-mcp-server && bun install
  cp .env.example .env   # optionally set CROSSREF_MAILTO
  

• 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
  

Docker

docker run --rm -e [email protected] -p 3010:3010 ghcr.io/cyanheads/crossref-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/crossref-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/crossref-mcp-server:latest"]. To build locally, docker build -t crossref-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

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

• Handlers throw, framework catches — no try/catch in tool logic
• 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.