Skip to main content
Glama
crossref-mcp-server

crossref-mcp-server

by cyanheads

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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

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, related identifiers, clinical trial numbers, Crossmark assertions, and — where deposited — a proceedings paper's conference event, a dissertation's or standard's approved date, a thesis's or preprint's institutions, a thesis's degree, a preprint's subtype and groupTitle, a grant's award, projects, and investigators, a peer review's review details, and a preprint's publishedVersions

crossref_search_works

Search the Crossref works index by free text and/or structured filters, with field-scoped query parameters, sort, field selection, per-value counts (facets), 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 the publisher that registered it, chaining into crossref_get_member

Resources

Resource

Description

skill://crossref-guide/SKILL.md

Agent Skill crossref-guide: judgment for the crossref_* tools — confirming a citation match, choosing between the journal/funder works lists and a filtered works search, Crossref filter syntax, DOI prefix versus current publisher, and deposit-dependent coverage

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/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 — 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 larger limit is clamped to 10,000 with a notice); authorCount / investigatorCount report the full deposited total and a nextOffset continues when entries remain — every other field, lead and co-lead investigators included, is returned in full on every page

  • A grant, which deposits no title or abstract, carries award, awardStart, and projects (titles, descriptions, lead, co-lead, and other investigators, amounts, start and end dates, and funding, each funder with its Funder Registry DOI or ROR); its published is the award start. A peer review carries review — 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's notice names crossref_get_work as the route to it

  • 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

  • On a posted-content record of subtype preprint, publishedVersions lists the works whose own records name the preprint in has-preprint — its published version, doi with type and title where present — read by one extra request (every other record takes one request), at most 10 with the notice giving the total and the crossref_search_works filter that lists them all. [] means no Crossref record names the preprint; the field is omitted when the lookup failed, which the notice says does not mean there is none. A preprint's own relations can omit its published version, and publishedVersions is not deduplicated against them

  • 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 25 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. Three of the 25 are opt-in and come back only when named: funder (funders and funderCount, at most 25 funders per work, funderCount the deposited total — crossref_get_work returns the whole list), license (licenses), and link (links), each in the entry shape crossref_get_work uses, 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 its notice

  • 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 200 works per call when fields names funder, license, or link, otherwise up to 500, 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, a grant row's missing title explained in the page's notice (crossref_get_work returns it); 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, plus, on a funder_doi lookup, worksCount and descendantWorksCount, both less grant records

  • 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. Both that list and the filter count every grant DOI a funder registers as a funded work. The lookup's worksCount is the filter's total less its grant records, and descendantWorksCount the funded-works list's total (fundedWorksTotal) less its grant records; to count without grants under other filters, call crossref_search_works with rows: 0 and subtract from totalResults the Grant count of facets {"type-name": "*"} (or the totalResults of 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 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 an attempt that hits CROSSREF_TIMEOUT_MS are not retried, and a request's attempts, backoffs, and Retry-After waits share one 25 s deadline (CROSSREF_TIMEOUT_MS when 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 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, HTML escaped into those fields (&lt;p&gt;) is stripped like deposited markup, except a lone opener that names an element (Use of &lt;i&gt;), 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 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.

Variable

Description

Default

CROSSREF_MAILTO

Email address embedded in the polite-pool User-Agent header of every Crossref request. Optional — server starts without it but logs a warning and uses the anonymous pool with stricter rate limits. Never sent to doi.org: the agency lookup and the citation request after a Crossref not-found identify the server and version only.

—

CROSSREF_BASE_URL

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 https://doi.org, whatever this is set to.

https://api.crossref.org

CROSSREF_TIMEOUT_MS

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.

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

LOG_TOOL_FAILURE_PAYLOADS

Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.

false

OTEL_ENABLED

Enable OpenTelemetry instrumentation.

false

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 CROSSREF_MAILTO=your-email@example.com -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

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.

skills/

Published Agent Skill (crossref-guide), served over MCP and shipped with the package.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Searches and retrieves scholarly metadata from the CrossRef REST API, covering over 150 million records across all disciplines, without requiring an API key.
      37 PyPI
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables searching and retrieving scholarly metadata from Crossref's public REST API, including works, journals, funders, and members, without requiring an API key.
      10
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching academic papers, journals, and citations via the Crossref API, and resolving DOIs to canonical metadata with authors, references, and citation graphs.
      114 npm
      MIT