Tools

Seven tools for working with Crossref data — DOI resolution, full-text search across all scholarly works, outgoing reference lists, and journal, funder, and publisher lookup:

crossref_get_work

Resolve a DOI to its canonical Crossref record.

• DOI validated against 10.NNNN/suffix regex before the upstream call
• Returns title, authors with affiliations, abstract (when deposited), container/journal, publication date, work type, ISSN, license URLs, full-text link URLs, and funder acknowledgements
• Outgoing references are reported as a count; the entries themselves come from crossref_get_references
• Incoming citation count (is-referenced-by-count) is included; citing works are not — Crossref does not expose that data. Use OpenAlex for citation graphs.

crossref_search_works

Search across ~155M Crossref-registered works.

• Free-text query plus a structured filter object using Crossref's hyphen-separated key syntax: from-pub-date, until-pub-date, type, funder, issn, member, has-abstract, has-references, has-full-text, directory (use DOAJ to restrict to open-access content)
• Field-specific query parameters scope matching beyond the generic query: queryTitle, queryAuthor, queryContainerTitle (journal/book name), and queryBibliographic (whole-citation match to resolve a known reference to its DOI) — all combine with each other and with query
• Sort by relevance, is-referenced-by-count, published, deposited, or score
• fields parameter narrows response payload — useful for large result sets. Names are case-sensitive; DOI is always returned whether or not it is listed, so every result stays resolvable by crossref_get_work.
• Offset paging up to ~10K results; deep paging requires cursor=* on the first call, then pass the returned nextCursor token. Cursor and offset cannot be combined.
• A cursor walk ends on the page that omits nextCursor. Crossref keeps minting a token past the end of a list, so the token is withheld on an empty page rather than relayed — the rule the works_cursor walks below follow too. Here that page also carries a notice saying the walk is complete, because works is this tool's whole payload and an empty page nothing is said about renders as blank text.

crossref_get_references

Fetch the outgoing reference list for a DOI.

• Each reference includes its raw citation string and, where Crossref has resolved it, a DOI for follow-up lookup
• Paged with offset and limit (default 100, max 500). referenceCount is the full deposited total; when more remain, the response carries a nextOffset to pass back as offset. Most works fit in a single page — bibliography records can carry tens of thousands of references.
• Coverage varies by publisher — pre-2000 literature and non-participating publishers may have no reference list
• Single-hop only; agents that need N-hop traversal chain calls explicitly

crossref_search_journals

Find journal records by ISSN or title.

• include_works: true also returns a page of the journal's most recent works by publication date
• Returns journal title, publisher, ISSN-L, subject areas, and total DOI count
• Title-query results page with offset; journalsTotal reports the full match count and nextOffset carries the input for the following page. The journal works list pages separately with works_offset and nextWorksOffset.
• The two lists have different ceilings: title search allows offset + rows up to 100,000, the works list only 10,000. A page that stops at either ceiling carries a notice saying so — a missing continuation offset would otherwise read as the end of the list.
• The journal works list also pages by cursor, which has no ceiling: pass works_cursor="*" and chain the nextWorksCursor token from each response to read the whole list. A cursor walk starts at the newest work and cannot resume from an offset, and the two cannot be combined — works_cursor with a nonzero works_offset returns works_cursor_offset_conflict. Each token runs about 1500 characters on both result surfaces, a cost per page rather than per record, so a long walk is cheaper at a high rows.
• include_works needs an unambiguous journal. A title query matching more than one — measured by the upstream match count, not by how many fit on the requested page — returns ambiguous_journal, naming the page's candidates and their ISSNs in the message and in candidates on the error data, alongside the full match count. Pass one back as issn, or narrow the query when the journal you want is not among them.

crossref_search_funders

Find funders in the Crossref Funder Registry.

• Accepts a name query, a bare registry ID (100000001), or a full funder DOI (10.13039/100000001, optionally behind a doi: or https://doi.org/ prefix)
• include_works: true also returns a page of works funded by the matched funder
• Returns funder name, registry ID, country, and alternate names
• Name-query results page with offset; fundersTotal reports the full match count and nextOffset carries the input for the following page. The funded works list pages separately with works_offset and nextWorksOffset.
• The two lists have different ceilings: name search allows offset + rows up to 100,000, the works list only 10,000. A page that stops at either ceiling carries a notice saying so — a missing continuation offset would otherwise read as the end of the list.
• The funded works list also pages by cursor, which has no ceiling: pass works_cursor="*" and chain the nextWorksCursor token from each response to read the whole list. A cursor walk starts at the newest work and cannot resume from an offset, and the two cannot be combined — works_cursor with a nonzero works_offset returns works_cursor_offset_conflict. Each token runs about 1500 characters on both result surfaces, a cost per page rather than per record, so a long walk is cheaper at a high rows. This list counts works funded by the funder's registry descendants, which a crossref_search_works filter on {"funder": "10.13039/<id>"} does not.
• include_works needs an unambiguous funder. A name query matching more than one — measured by the upstream match count, not by how many fit on the requested page — returns ambiguous_funder rather than resolving one silently, naming the page's candidates and their registry IDs in the message and in candidates on the error data, alongside the full match count. Pass one back as funder_doi, or narrow the query when the funder you want is not among them.

crossref_get_member

Resolve a Crossref member ID to its publisher/organization record.

• 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

Resolve a DOI prefix to its owning publisher.

• 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:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Crossref-specific:

• Polite-pool User-Agent header injected on every request — priority access granted via CROSSREF_MAILTO email address, no API token required
• Retry with exponential backoff on 429 (honoring Retry-After), 5xx, HTTP 408/504, and network failures. Two failures are not retried: a malformed response body, which an identical request re-serializes, and a request that hits CROSSREF_TIMEOUT_MS, where every attempt costs the full deadline
• Upstream failures arrive classified and with recovery guidance on both result surfaces: rate limit, service unavailable, timeout, and malformed response each say what to do next in content[] as well as in structuredContent
• Cursor-based deep paging on the works search and on both works sub-resources, for result sets beyond the offset cap
• Filter key validation: Crossref uses hyphens (has-abstract, has-references, from-pub-date); the server enforces correct syntax and surfaces API validation errors with actionable recovery hints

Getting started

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.

{
  "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):

{
  "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:

{
  "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.3.14 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

1. Clone the repository:

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

2. Navigate into the directory:

cd crossref-mcp-server

3. Install dependencies:

bun install

4. 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.

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

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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.