crossref-mcp-server
Resolves DOIs to full Crossref metadata records, including titles, authors, affiliations, abstracts, journals, publication dates, licenses, full-text links, and funder acknowledgements.
Public Hosted Server: https://crossref.caseyjhand.com/mcp
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
Tool | Description |
| 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, related identifiers, clinical trial numbers, Crossmark assertions, and — where deposited — a proceedings paper's conference |
| Search the Crossref works index by free text and/or structured filters, with field-scoped query parameters, sort, field selection, per-value counts ( |
| Return the outgoing reference list for a DOI — the works cited by this paper, with citation strings and resolved DOIs where available |
| Find Crossref journal records by ISSN or title query; optionally retrieve a page of the journal's most recent works |
| Find funders in the Crossref Funder Registry by name, registry ID, or funder DOI; optionally retrieve a page of funded works |
| Resolve a Crossref member ID to its publisher record — name, owned DOI prefixes, DOI counts, and per-category metadata deposit coverage |
| Resolve a DOI prefix (e.g. |
Resources
Resource | Description |
| Agent Skill |
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.
Related MCP server: CrossRef MCP Server
Capability reference
crossref_get_work tool
DOI validated against the
10.NNNN/suffixregex before the upstream call, accepted either bare or wrapped in its resolver (https://doi.org/…,https://dx.doi.org/…,doi:…) and unwrapped before the lookupReturns title, authors with affiliations, abstract (when deposited), container/journal, publication date, work type, ISSN, license URLs, full-text link URLs, and funder acknowledgements
containerTitleslists 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 — besidecontainerTitle, which keeps the first;crossref_search_worksreturns both, and itscontainer-titleselect name fills bothCitation locators
volume,issue,page, andarticleNumberunder the same names and on the same rendered line ascrossref_search_works, plusisbn— each as deposited, omitted when absentmemberIdis the Crossref member that holds the DOI now — pass it tocrossref_get_memberfor the publisher record. For a title transferred to another publisher it differs from the member the DOI's prefix names throughcrossref_get_prefixeditorsin the author entry shape, returned whole and never counted inauthorCountAuthor list — and on a grant, which deposits no authors, the investigators of its projects as one list in deposited order — paged by
offset/limit(default 25, up to 10,000 per call — a largerlimitis clamped to 10,000 with anotice);authorCount/investigatorCountreport the full deposited total and anextOffsetcontinues when entries remain — every other field, lead and co-lead investigators included, is returned in full on every pageA grant, which deposits no title or abstract, carries
award,awardStart, andprojects(titles, descriptions, lead, co-lead, and other investigators, amounts, start and end dates, and funding, each funder with its Funder Registry DOI or ROR); itspublishedis the award start. A peer review carriesreview— stage, type, running number, revision round, recommendation, competing-interest statement, and language — where deposited. The works lists carry neither: a grant row there has no title and the page'snoticenamescrossref_get_workas the route to itupdatedBylists the corrections, retractions, expressions of concern, and new versions Crossref records against the work — notice DOI, type, source (publisherorretraction-watch, with its record ID), and date, entry for entry — andupdateTothe works this record is a notice for; whenupdatedByis present,noticenames each update type with its sources. An absentupdatedBydoes not mean the work was never updatedrelationsgroups 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 toolOn a
posted-contentrecord of subtypepreprint,publishedVersionslists the works whose own records name the preprint inhas-preprint— its published version,doiwithtypeandtitlewhere present — read by one extra request (every other record takes one request), at most 10 with thenoticegiving the total and thecrossref_search_worksfilter that lists them all.[]means no Crossref record names the preprint; the field is omitted when the lookup failed, which thenoticesays does not mean there is none. A preprint's ownrelationscan omit its published version, andpublishedVersionsis not deduplicated against themclinicalTrialNumbers(number,registry,type) lists the trial registrations the work names, andassertionsthe Crossmark entries its publisher attaches — article-history dates, ethics and competing-interest statements (told apart bygroupLabel), peer-review details, boilerplate — each returned whole in deposited order, a repeated entry included, and omitted when not deposited. An assertion'svalueis normalized text, never parsed into a date; itsurlis omitted where it repeatsvalue; Crossref's per-grouporderis not carried, since array order is the sequence. A missingclinicalTrialNumbersdoes not mean the work reports no trialevent(name, acronym, location,start,end) is the conference a proceedings paper was presented at, andcrossref_search_worksreturns 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, andgroupTitlearecrossref_get_workonly, since Crossref refusesinstitutionandsubtypeasselectnames. Each is omitted when the record deposits noneA funder, affiliation, or institution asserted only through the ROR registry (no name deposited) carries
rorin place ofname, never as a blank entryPublication date is the first of
published,published-print,published-online, andissued(this tool only) that names a value; a date component Crossref records as unknown is omitted, along with everything less precise below it.approvedis 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 noneOutgoing references are reported as a count (
referencesCount) — entries come fromcrossref_get_references; incoming citation count (isReferencedByCount) is included, but citing works are not exposed by Crossref — use OpenAlex for citation graphsA DOI Crossref holds no record for returns
doi_not_foundnaming 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.citationand the message): title, authors (the first 25, withauthorCount), container title, issued date, publisher, and type, each where the agency has one
crossref_search_works tool
Free-text
queryplus a structuredfilterobject using Crossref's hyphenated keys (from-pub-date,type,funder,issn,has-abstract,license.url, etc.); dissertations and most standards depositapprovedrather than a publication date, so bound them withfrom-approved-date/until-approved-date, which the pub-date filters do not readField-scoped parameters
queryTitle,queryAuthor,queryContainerTitle, andqueryBibliographiccombine withqueryand with each otherSort by
relevance,score,is-referenced-by-count,published,deposited, or other listed fields — the publication-date sorts page byoffsetonly, since Crossref refuses them with a cursor. A cursor walk with a query term and nosortruns by relevance (sent assort=score, withoutorder) and can repeat or skip a record at a page boundary;sort: "created"walks without repeats. A filter-only walk runs in Crossref registration orderCrossref's own parameter names are accepted as input aliases:
selectforfields, andquery.bibliographic,query.title,query.author,query.container-titlefor the four field-scoped parametersfieldsnarrows the payload to any of the 25 select names the summary projects — including the citation locatorsvolume,issue,page,article-number, andISSN, the update linksupdated-byandupdate-to,approved,event, andmemberformemberId, which every work also carries whenfieldsis omitted — and refuses any other name;DOIis always returned, andcrossref_get_workcarries the rest of the record. Three of the 25 are opt-in and come back only when named:funder(fundersandfunderCount, at most 25 funders per work,funderCountthe deposited total —crossref_get_workreturns the whole list),license(licenses), andlink(links), each in the entry shapecrossref_get_workuses, so a funder-mandate or license check reads a page of works rather than one call per DOI. A grant row has no title, and a page carrying one says so in itsnoticeEach work carries
updatedBy(corrections, retractions, expressions of concern, new versions recorded against it) andupdateTo(the works it is a notice for) in the entry shape and rendered linecrossref_get_workuses, so a page of results can be screened for retractions without a call per DOIA blank or whitespace-only query term or filter value, and an empty
sortororder, is read as omitted; when that leaves nothing to search by, thenoticesays the page is an unfiltered listingrowsreturns up to 200 works per call whenfieldsnamesfunder,license, orlink, otherwise up to 500, or up to 1,000 whenfieldsnames neitherabstractnorauthor, andauthorLimitcaps authors per work (default 25, up to 500); a larger value of either is clamped to its cap with anotice, which on an offset page also names the offset that continues after the records returned;authorCountreports the full deposited total — chain a cut work's DOI intocrossref_get_workfor the restfacetscounts 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 recordtotalResultscounts, 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 anotice, and a facet whose values reach its limit is named there as one that may have more; Crossref'svalue-countcounts the values returned, so no distinct total is reported.rows: 0returns the counts andtotalResultswith no works, and leaves a cursor walk where it wasOffset paging is capped at
offset + rows ≤ 10,000: a page that would pass it returns therowsthat fit, with anoticenaming the rows requested and applied, and an offset of 10,000 or more is refused (offset_too_large);cursor="*"starts deep paging via chainednextCursortokens — cursor and offset cannot be combinedA cursor walk ends on the page that omits
nextCursor— an empty page never carries one; every empty page'snoticenames which of the three causes applies, except arows: 0page, 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_workacceptsEach reference carries its deposited citation string and, when Crossref has resolved it, a DOI for
crossref_get_work, withdoiAssertedBysaying whether the publisher deposited that DOI or Crossref matched itStructured 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 ISSNCitation 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 largerlimitis clamped to 4,000 with anotice);referenceCountis the full deposited total andnextOffsetcontinues when more remainCoverage 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_foundnaming its registration agency (registrationAgency), or saying no agency registered it, the same waycrossref_get_workdoes; a DOI registered with DataCite, JaLC, mEDRA, KISTI, or OP carries its citation (data.citationand the message) as well
crossref_search_journals tool
include_works: truealso returns a page of the journal's most recent works, drawn from every ISSN its record lists whichever one was passed — newest published first byworks_offset, newest registered first on aworks_cursorwalk; requires an unambiguous journal — a title query matching more than one returnsambiguous_journal, naming candidates and ISSNsrowstakes up to 1,000, for the title-query journal list and theinclude_workslist alikeReturns 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_membergives per publisherAn
issnlookup also returns DOI counts by issued year, ascending; title-query results omit themTitle-query results page by
offset(ceilingoffset + rows ≤ 100,000); the works list pages separately byworks_offset(ceiling≤ 10,000) — a page that would pass either ceiling returns therowsthat fit, with anoticenaming 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 anoticenaming it, and so does a page that reaches either ceiling with records past itworks_cursor="*"pages the works list with no ceiling via chainednextWorksCursortokens; a cursor walk runs by Crossref registration date, newest first (Crossref does not walk a publication-date sort by cursor), and cannot combine withworks_offset > 0(works_cursor_offset_conflict)A matched journal with no well-formed ISSN registered has no addressable works list —
include_worksis skipped with anoticerather 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 adoi:/https://doi.org/prefix)include_works: truealso returns a page of funded works, a grant row's missing title explained in the page'snotice(crossref_get_workreturns it); requires an unambiguous funder — a name query matching more than one returnsambiguous_funder, naming candidates and registry IDsReturns funder name, registry ID, country, and alternate names, plus, on a
funder_doilookup,worksCountanddescendantWorksCount, both less grant recordsName-query results page by
offset(ceiling≤ 100,000); the funded-works list pages separately byworks_offset(ceiling≤ 10,000) or, with no ceiling,works_cursor="*"chainingnextWorksCursor— 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 therowsthat fit, with anoticenaming 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 anoticenaming it, and so does a page that reaches either ceiling with records past itThe funded-works list also counts works funded by the funder's registry descendants, which a
crossref_search_worksfilter on{"funder": "10.13039/<id>"}does not; afunder_doilookup returns those descendants' registry IDs asdescendants, every depth, whole — OR'd with the funder's ID in thefunderfilter they count the same scope with date, type, or other filters. Both that list and the filter count every grant DOI a funder registers as a funded work. The lookup'sworksCountis the filter's total less its grant records, anddescendantWorksCountthe funded-works list's total (fundedWorksTotal) less its grant records; to count without grants under other filters, callcrossref_search_workswithrows: 0and subtract fromtotalResultstheGrantcount offacets{"type-name": "*"}(or thetotalResultsof the same call with"type": "grant"added to the filter)A deprecated registry entry answers to its successor's name while counting only its own works — the response's
noticenames the superseding ID viareplacedBy; the replacement is never followed automaticallyA funder's
replacesIDs are counted by neither the funded-works list nor thefunderfilter 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
memberIdcrossref_get_workorcrossref_search_worksreturns for it;crossref_get_prefixreturns 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_memberfor the full record. A DOI under a title transferred to another publisher keeps its prefix, so its current member is thememberIdcrossref_get_workreturnsThe 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_foundnaming the agency that registered it (registrationAgency, e.g. DataCite for10.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-Agentheader injected on every Crossref request — priority access viaCROSSREF_MAILTO, keyless otherwise; no API token requiredRetry with exponential backoff on 429 (honoring
Retry-After), 5xx, HTTP 408/504, and network failures; a malformed response body and an attempt that hitsCROSSREF_TIMEOUT_MSare not retried, and a request's attempts, backoffs, andRetry-Afterwaits share one 25 s deadline (CROSSREF_TIMEOUT_MSwhen longer)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 malformedissnfilter value is refused before the request, and no upstream error relays Crossref's raw response bodyText 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, HTML escaped into those fields (
<p>) is stripped like deposited markup, except a lone opener that names an element (Use of <i>), which stays as written, and an escaped tag in a citation string stays as the publisher typed it; 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 asx_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-verificationGraceful 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
noticesaying which, and so does the page that ends acrossref_search_workscursor walk; a journal or funder works walk ends on the page that omitsnextWorksCursorDiscriminated output contracts — the
nextCursor,nextOffset,nextWorksOffset, andnextWorksCursorcontinuation fields are withheld once a list is exhausted, a page that reaches an offset ceiling says so in itsnotice, 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 noneAmbiguity handled explicitly —
ambiguous_journalandambiguous_funderlist 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/mcpOr run it locally:
claude mcp add crossref-mcp-server -- npx -y @cyanheads/crossref-mcp-serverFor 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.
Variable | Description | Default |
| Email address embedded in the polite-pool | — |
| Crossref API base URL. Override for testing against a local proxy. The agency lookup and the citation request after a Crossref not-found always go to |
|
| Per-attempt timeout in milliseconds; an attempt that hits it is not retried. A request's retries share one deadline: 25 s, or this value when it is longer. Above 25000, a call that chains two requests can outlast the 60 s MCP clients wait by default. |
|
| Transport: |
|
| HTTP session mode: |
|
| Port for the HTTP server. |
|
| Auth mode: |
|
| Log level (RFC 5424). |
|
| Directory for log files (Node.js only). |
|
| Log each failed tool call's arguments and result, redacted by key name and capped at |
|
| Enable OpenTelemetry instrumentation. |
|
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_MAILTOBuild and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:httpRun 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 CROSSREF_MAILTO=your-email@example.com -p 3010:3010 ghcr.io/cyanheads/crossref-mcp-server:latestThe 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
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| CrossrefService — HTTP client, polite-pool header, retry, pagination helpers. |
| Published Agent Skill ( |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageRegister new tools via the barrel in
src/mcp-server/tools/definitions/index.tsWrap 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 testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search 150M+ academic works, journals, and funders via Crossref API.
Unofficial Crossref MCP — wraps the Crossref REST API (academic papers, free, no auth)
Verify a DOI or find papers via Crossref metadata. $0.005/call via x402.
Search DataCite datasets and software, fetch DOI metadata, trace relations, format citations.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables retrieval of academic literature metadata via DOI or search using the Crossref REST API.2MIT
- AlicenseNot gradedqualityDmaintenanceSearches and retrieves scholarly metadata from the CrossRef REST API, covering over 150 million records across all disciplines, without requiring an API key.37 PyPIMIT
- FlicenseAqualityDmaintenanceEnables searching and retrieving scholarly metadata from Crossref's public REST API, including works, journals, funders, and members, without requiring an API key.101-
- AlicenseNot gradedqualityBmaintenanceEnables searching academic papers, journals, and citations via the Crossref API, and resolving DOIs to canonical metadata with authors, references, and citation graphs.114 npmMIT