How do I use crossref-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@crossref-mcp search for works by author 'Einstein'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

crossref-mcp

by jtl-neo

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

crossref-mcp

License: MIT Docker

English | 中文

An MCP server wrapping the Crossref REST API, exposing scholarly-metadata lookups (works, members, journals, funders, types, licenses, prefixes) as tools an LLM client can call.

Not affiliated with or endorsed by Crossref. Data is served live from the public Crossref API. Set CROSSREF_MAILTO to join Crossref's polite pool.

Features

All major Crossref resource endpoints as 18 read-only tools.
Dual transport: stdio (local) and Streamable HTTP (container).
Polite pool (User-Agent + mailto), optional Crossref Plus token.
Token-bucket rate limiting (auto-tuned from X-Rate-Limit-* headers) with exponential backoff honoring Retry-After.
Cursor deep paging, field select, raw vs simplified output.
Optional X-API-Key HTTP auth (/health exempt), /health endpoint.
Optional Redis response cache + cross-replica rate limiting.
Optional Caddy TLS reverse proxy for public deployment.

Related MCP server: crossref-mcp

Quick start (local, stdio)

uv sync
export CROSSREF_MAILTO="you@example.com"   # recommended (polite pool)
uv run crossref-mcp                         # starts a stdio MCP server

Inspect with the MCP Inspector: uv run mcp dev src/crossref_mcp/server.py.

Configuration

Env var	Required	Default	Description
`CROSSREF_MAILTO`	recommended	—	Email for Crossref's polite pool.
`CROSSREF_PLUS_TOKEN`	no	—	Crossref Plus API token (sent as a header).
`CROSSREF_BASE_URL`	no	`https://api.crossref.org`	API base URL.
`CROSSREF_TIMEOUT`	no	`30`	Per-request timeout (seconds).
`MCP_TRANSPORT`	no	`stdio`	`stdio` or `http`.
`MCP_API_KEY`	no	—	If set, HTTP requests need a matching `X-API-Key` header (`/health` exempt).
`LOG_LEVEL`	no	`INFO`	Log level (logs go to stderr).
`REDIS_URL`	no	—	Enable Redis cache + shared rate limiting (optional).
`CACHE_TTL`	no	`86400`	Cache TTL in seconds.
`RATELIMIT_BACKEND`	no	`in-memory`	`in-memory` or `redis`.

Tools

Works — search_works, get_work (by DOI), get_work_references (capped at 50), get_work_quality (registration agency). Members / Journals / Funders — search_members · get_member · get_member_works; search_journals · get_journal (ISSN) · get_journal_works; search_funders · get_funder · get_funder_works. Types / Licenses / Prefixes — list_types · get_type; list_licenses; get_prefix. Plus ping.

Shared parameters. Search/list tools take query (and query_bibliographic / query_author / query_title on works), filter (Crossref key:value,… syntax), sort + order, rows (≤1000) + offset, and select. Deep paging: set cursor="*" then reuse the returned next_cursor. All tools return simplified fields by default; pass raw=true for the full Crossref JSON.

Connecting an MCP client

stdio (Claude Desktop / Cursor) — claude_desktop_config.json:

{
  "mcpServers": {
    "crossref": {
      "command": "uvx",
      "args": ["crossref-mcp"],
      "env": { "CROSSREF_MAILTO": "you@example.com" }
    }
  }
}

Or run the container over stdio: "command": "docker", "args": ["run", "-i", "--rm", "-e", "CROSSREF_MAILTO", "heyinnaneo/crossref-mcp"].

Streamable HTTP — once the container is up, point an HTTP-capable client at http://localhost:8000/mcp. If MCP_API_KEY is set, send it as X-API-Key.

Use as a skill (no server)

Prefer not to run a server? skill.md is a self-contained skill that teaches an agent to call the Crossref REST API directly — it only needs an HTTP/fetch capability (no install, no key, no container). Trade-off: the agent issues raw HTTP and parses Crossref JSON itself, without the MCP server's polite-pool throttling, field simplification, or structured errors.

Claude Code (Agent Skill):

mkdir -p ~/.claude/skills/crossref-api
curl -fsSL https://raw.githubusercontent.com/jtl-neo/crossref-api-MCP/main/skill.md \
  -o ~/.claude/skills/crossref-api/SKILL.md

(Project-scoped instead: place it at .claude/skills/crossref-api/SKILL.md in your repo.)

Other agents (Cursor, Claude Projects, custom): paste the contents of skill.md into your system prompt / project knowledge / rules file.

Docker / HTTP deployment

cp .env.example .env          # set CROSSREF_MAILTO
docker compose up -d          # pulls heyinnaneo/crossref-mcp, HTTP on :8000
curl http://localhost:8000/health

Serves Streamable HTTP at /mcp and /health (compose health check). Set MCP_API_KEY to require X-API-Key on /mcp. To build locally, uncomment build: . in docker-compose.yml.

Public deployment (TLS / reverse proxy) — optional

Put it behind the bundled Caddy proxy (Caddyfile + docker-compose.proxy.yml): TLS termination (auto Let's Encrypt), HTTP→HTTPS, SSE streaming, backend not published on the host.

cp .env.example .env   # add DOMAIN=, ACME_EMAIL=, MCP_API_KEY=
docker compose -f docker-compose.proxy.yml up -d
curl https://your-domain/health

Defense in depth: proxy edge (optional IP allowlist / Basic auth) + MCP_API_KEY app layer; both leave /health open. Needs a domain with DNS pointing at the host and ports 80/443 reachable. Caddy rate limiting needs the caddy-ratelimit plugin (custom build).

Redis cache + cross-replica rate limiting — optional

Set REDIS_URL for a response cache (cache-aside on the raw envelope; mailto/ secrets excluded from keys) and, with RATELIMIT_BACKEND=redis, a shared token bucket so replicas stay within Crossref's polite-pool rate.

docker compose -f docker-compose.redis.yml up -d
curl http://localhost:8000/health   # cache_enabled + ratelimit_backend + redis: up

Redis failures degrade gracefully (no cache, in-memory limiting); /health stays 200 with redis: down.

CI / publishing

.github/workflows/ci.yml: test (ruff + format + pytest with coverage on every push/PR), security (Trivy fs scan), build-push (multi-arch image to heyinnaneo/crossref-mcp on main / v* tags), and on tags publish-pypi (OIDC Trusted Publisher) + publish-registry (MCP registry).

Repository secrets (Settings → Secrets and variables → Actions): DOCKERHUB_USERNAME = heyinnaneo, DOCKERHUB_TOKEN = a Docker Hub Access Token (Read/Write). Tag a release (git tag v0.1.0 && git push origin v0.1.0); the tag must match pyproject.toml.

Install from the MCP registry

Published as io.github.jtl-neo/crossref-mcp (see server.json), with a PyPI package (uvx crossref-mcp) and an OCI image. Publishing is automated on version tags (publish-pypi + publish-registry); requires a public repo and a configured PyPI Trusted Publisher.

Security & trust

Read-only. Every tool is a lookup, annotated readOnlyHint.
Rate limiting. Single-process in-memory by default — don't run as a public proxy for heavy traffic; for replicas use RATELIMIT_BACKEND=redis.
Polite pool. Use your own CROSSREF_MAILTO.
Public HTTP. Set MCP_API_KEY and front with TLS.
No bundled secrets. .env is excluded from image and git.

License

MIT. Bibliographic data comes from the public Crossref REST API; not affiliated with Crossref.

中文

English | 中文

把 Crossref REST API 封裝成 MCP server，將學術文獻 metadata 查詢（works、members、journals、funders、types、 licenses、prefixes）包成 LLM client 可呼叫的工具。

非 Crossref 官方、未經其背書。資料即時取自公開的 Crossref API。請設定 CROSSREF_MAILTO 以加入 Crossref 的 polite pool。

特色

主要 Crossref 資源端點，共 18 個唯讀工具。
雙傳輸：stdio（本機）與 Streamable HTTP（容器）。
Polite pool（User-Agent + mailto）、可選 Crossref Plus token。
Token-bucket 速率控制（依 X-Rate-Limit-* header 自動調整），429 指數退避並尊重 Retry-After。
cursor 深分頁、欄位 select、raw 與精簡輸出切換。
可選 X-API-Key HTTP 認證（/health 豁免）、/health 端點。
可選 Redis 回應快取 + 跨副本速率控制。
可選 Caddy TLS 反向代理，供公開部署。

快速開始（本機 stdio）

uv sync
export CROSSREF_MAILTO="you@example.com"   # 建議（polite pool）
uv run crossref-mcp                         # 啟動 stdio MCP server

用 MCP Inspector 檢視：uv run mcp dev src/crossref_mcp/server.py。

設定

環境變數	必填	預設	說明
`CROSSREF_MAILTO`	建議	—	Crossref polite pool 用的 email。
`CROSSREF_PLUS_TOKEN`	否	—	Crossref Plus API token（以 header 送出）。
`CROSSREF_BASE_URL`	否	`https://api.crossref.org`	API base URL。
`CROSSREF_TIMEOUT`	否	`30`	每請求逾時（秒）。
`MCP_TRANSPORT`	否	`stdio`	`stdio` 或 `http`。
`MCP_API_KEY`	否	—	設了則 HTTP 請求需帶相符的 `X-API-Key` header（`/health` 豁免）。
`LOG_LEVEL`	否	`INFO`	日誌層級（日誌走 stderr）。
`REDIS_URL`	否	—	啟用 Redis 快取 + 共享速率控制（選用）。
`CACHE_TTL`	否	`86400`	快取 TTL（秒）。
`RATELIMIT_BACKEND`	否	`in-memory`	`in-memory` 或 `redis`。

工具

Works — search_works、get_work（依 DOI）、get_work_references（上限 50）、get_work_quality（註冊機構）。 Members / Journals / Funders — search_members／get_member／ get_member_works；search_journals／get_journal（ISSN）／get_journal_works； search_funders／get_funder／get_funder_works。 Types / Licenses / Prefixes — list_types／get_type；list_licenses； get_prefix。另有 ping。

共用參數。 搜尋／列表工具接受 query（works 另有 query_bibliographic／ query_author／query_title）、filter（Crossref key:value,… 語法）、sort

order、rows（≤1000）+ offset、select。深分頁：設 cursor="*"，再把回傳的 next_cursor 傳回續抓。所有工具預設回精簡欄位；傳 raw=true 取完整 Crossref JSON。

連接 MCP client

stdio（Claude Desktop / Cursor） — claude_desktop_config.json：

{
  "mcpServers": {
    "crossref": {
      "command": "uvx",
      "args": ["crossref-mcp"],
      "env": { "CROSSREF_MAILTO": "you@example.com" }
    }
  }
}

或以容器跑 stdio："command": "docker"、"args": ["run", "-i", "--rm", "-e", "CROSSREF_MAILTO", "heyinnaneo/crossref-mcp"]。

Streamable HTTP — 容器啟動後，將支援 HTTP 的 client 指向 http://localhost:8000/mcp。若設了 MCP_API_KEY，以 X-API-Key header 帶上。

當作 skill 使用（免 server）

不想架 server？skill.md 是自包含 skill，教 agent 直接呼叫 Crossref REST API — 只需 agent 有 HTTP/fetch 能力（免安裝、免 key、免容器）。取捨：agent 自己發 raw HTTP、自己解析 Crossref JSON，沒有 MCP server 的 polite-pool 限速、欄位精簡、結構化錯誤。

Claude Code（Agent Skill）：

mkdir -p ~/.claude/skills/crossref-api
curl -fsSL https://raw.githubusercontent.com/jtl-neo/crossref-api-MCP/main/skill.md \
  -o ~/.claude/skills/crossref-api/SKILL.md

（專案層級：放 repo 內 .claude/skills/crossref-api/SKILL.md。）

其他 agent（Cursor / Claude Projects / 自製）： 把 skill.md 內容貼進 system prompt / project knowledge / rules 檔。

Docker / HTTP 部署

cp .env.example .env          # 設定 CROSSREF_MAILTO
docker compose up -d          # 拉 heyinnaneo/crossref-mcp，HTTP 在 :8000
curl http://localhost:8000/health

於 /mcp 提供 Streamable HTTP，/health 供 compose 健康檢查。設 MCP_API_KEY 可要求 /mcp 帶 X-API-Key。要本地 build，取消 docker-compose.yml 內 build: . 註解。

公開部署（TLS / 反向代理）— 選用

放在內附的 Caddy proxy 後（Caddyfile + docker-compose.proxy.yml）：TLS 終結（自動 Let's Encrypt）、HTTP→HTTPS、SSE 串流、後端不對 host 公開。

cp .env.example .env   # 加上 DOMAIN=、ACME_EMAIL=、MCP_API_KEY=
docker compose -f docker-compose.proxy.yml up -d
curl https://your-domain/health

縱深防禦：proxy 邊界（可選 IP allowlist / Basic auth）+ MCP_API_KEY 應用層；兩者皆留 /health 開放。需網域 DNS 指向主機、80/443 可達。Caddy 限流需 caddy-ratelimit plugin（自 build）。

Redis 快取 + 跨副本速率控制 — 選用

設 REDIS_URL 啟用回應快取（cache-aside 存原始 envelope；key 排除 mailto／密鑰），並以 RATELIMIT_BACKEND=redis 啟用共享 token bucket，讓多副本維持在 Crossref polite-pool 速率內。

docker compose -f docker-compose.redis.yml up -d
curl http://localhost:8000/health   # cache_enabled + ratelimit_backend + redis: up

Redis 故障會優雅降級（不快取、改 in-memory 限速）；/health 仍回 200 並標 redis: down。

CI / 發佈

.github/workflows/ci.yml：test（每次 push/PR 跑 ruff + format + pytest 含覆蓋率）、security（Trivy fs 掃描）、build-push（main／v* tag 時 push multi-arch image 到 heyinnaneo/crossref-mcp），打 tag 時另跑 publish-pypi （OIDC Trusted Publisher）+ publish-registry（MCP registry）。

Repository secrets（Settings → Secrets and variables → Actions）： DOCKERHUB_USERNAME = heyinnaneo、DOCKERHUB_TOKEN = Docker Hub Access Token （Read/Write）。打 tag 發版（git tag v0.1.0 && git push origin v0.1.0）；tag 須與 pyproject.toml 版本一致。

從 MCP registry 安裝

以 io.github.jtl-neo/crossref-mcp 發佈（見 server.json），含 PyPI 套件（uvx crossref-mcp）與 OCI image。發佈於版本 tag 時自動進行（publish-pypi + publish-registry）；需公開 repo 與已設定的 PyPI Trusted Publisher。

安全與信任

唯讀。 每個工具都是查詢，標註 readOnlyHint。
速率控制。 預設單 process in-memory — 勿當公開代理承載大流量；多副本請用 RATELIMIT_BACKEND=redis。
Polite pool。 用你自己的 CROSSREF_MAILTO。
公開 HTTP。 設 MCP_API_KEY 並前置 TLS。
不內含密鑰。 .env 不進 image、不進 git。

授權

MIT。文獻資料來自公開的 Crossref REST API；與 Crossref 無隸屬關係。

Available Tools

18 tools

get_funderA

Read-only

Fetch one funder by its Crossref Funder Registry id (e.g. 100000001).

Name	Required	Description	Default
`raw`	No
`funder_id`	Yes

get_funder_worksA

Read-only

List works funded by a given funder id.

Name	Required	Description	Default
`raw`	No
`rows`	No
`sort`	No
`order`	No
`query`	No
`cursor`	No
`filter`	No
`offset`	No
`funder_id`	Yes

get_journalA

Read-only

Fetch one journal by ISSN (NNNN-NNNN; hyphen optional).

Name	Required	Description	Default
`raw`	No
`issn`	Yes

get_journal_worksB

Read-only

List works published in a given journal (by ISSN).

Name	Required	Description	Default
`raw`	No
`issn`	Yes
`rows`	No
`sort`	No
`order`	No
`query`	No
`cursor`	No
`filter`	No
`offset`	No

get_memberA

Read-only

Fetch one member (publisher) by numeric Crossref member id.

Name	Required	Description	Default
`raw`	No
`member_id`	Yes

get_member_worksA

Read-only

List works published by a given member id.

Name	Required	Description	Default
`raw`	No
`rows`	No
`sort`	No
`order`	No
`query`	No
`cursor`	No
`filter`	No
`offset`	No
`member_id`	Yes

get_prefixA

Read-only

Look up the owner of a DOI prefix (e.g. "10.1038").

    Crossref only exposes /prefixes/{owner_prefix}; there is no list endpoint.

Name	Required	Description	Default
`raw`	No
`owner_prefix`	Yes

get_typeA

Read-only

Fetch one work type by id (e.g. "journal-article").

Name	Required	Description	Default
`raw`	No
`type_id`	Yes

get_workA

Read-only

Fetch a single work's metadata by DOI.

    Accepts a bare DOI or a doi.org URL. Returns simplified fields unless
    `raw=True`. Returns a structured error if the DOI does not exist.

Name	Required	Description	Default
`doi`	Yes
`raw`	No

get_work_qualityB

Read-only

Look up the registration agency for a DOI (Crossref, DataCite, ...).

Name	Required	Description	Default
`doi`	Yes
`raw`	No

get_work_referencesA

Read-only

List the reference list of a work (the works it cites), by DOI.

    `limit` is hard-capped at 50. Reads the `reference` field of the work.

Name	Required	Description	Default
`doi`	Yes
`raw`	No
`limit`	No

list_licensesA

Read-only

List licenses Crossref has seen. No single-license lookup exists.

Name	Required	Description	Default
`raw`	No
`rows`	No
`query`	No
`offset`	No

list_typesB

Read-only

List Crossref work types (journal-article, book-chapter, ...).

Name	Required	Description	Default
`raw`	No
`rows`	No
`offset`	No

pingA

Read-only

Health check tool: returns the server name and version.

Name	Required	Description	Default
No parameters

Output Schema

Name	Required	Description
`result`	Yes

search_fundersB

Read-only

Search funding bodies by name. Returns funder id, name, location.

Name	Required	Description	Default
`raw`	No
`rows`	No
`query`	No
`cursor`	No
`offset`	No

search_journalsB

Read-only

Search journals by title/keyword. Returns title, ISSNs, publisher.

Name	Required	Description	Default
`raw`	No
`rows`	No
`query`	No
`cursor`	No
`offset`	No

search_membersA

Read-only

Search Crossref members (publishers/societies). Returns id + primary name.

Name	Required	Description	Default
`raw`	No
`rows`	No
`query`	No
`cursor`	No
`filter`	No
`offset`	No

search_worksA

Read-only

Search Crossref works (articles, books, datasets, ...).

    Use `query` for free-text, or the field-scoped variants
    (query_bibliographic / query_author / query_title). `filter` accepts
    Crossref's `key:value,key2:value2` syntax (e.g. "from-pub-date:2020,type:journal-article").
    `rows` is capped at 1000; `select` (e.g. "DOI,title") trims the payload.
    For deep paging set `cursor="*"`, then pass the returned `next_cursor` back.
    Returns simplified items unless `raw=True`.

Name	Required	Description	Default
`raw`	No
`rows`	No
`sort`	No
`order`	No
`query`	No
`cursor`	No
`filter`	No
`offset`	No
`select`	No
`query_title`	No
`query_author`	No
`query_bibliographic`	No

Tool Schema Changelog

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

18 tool updatesv0.1.0Aug 6, 2026
- First observedget_funder
- First observedget_funder_works
- First observedget_journal
- First observedget_journal_works
- First observedget_member
- First observedget_member_works
- First observedget_prefix
- First observedget_type
- First observedget_work
- First observedget_work_quality
- First observedget_work_references
- First observedlist_licenses
- First observedlist_types
- First observedping
- First observedsearch_funders
- First observedsearch_journals
- First observedsearch_members
- First observedsearch_works

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-08-06 11:35 across 18 tools

Disambiguation4/5

Each tool targets a distinct entity (member, journal, funder, type, license, prefix, work). The only confusion is get_work_quality, which sounds like a quality metric but actually queries a DOI's registration agency; the description clarifies, but the name could mislead.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern (search_*, get_*, list_*), with consistent entity-specific suffixes like '_works'. The outlier is get_work_quality, which uses a non-entity noun and doesn't reflect its purpose; ping is also non-standard but acceptable.

Tool Count4/5

At 18 tools, this is slightly above the ideal 3-15 range, but the broad scope of Crossref's API—covering multiple entity types plus complex work search—justifies the count. No tool feels redundant or extraneous.

Completeness3/5

The set covers search and retrieval for members, journals, funders, works, types, licenses, and prefixes, including references. However, there is no endpoint for works citing a given DOI (forward citations), which is a notable gap for a scholarly metadata server.

Maintenance

ActivityNo data

ResponsivenessOutdated data

Resources

Related MCP Connectors

crossref-mcp-serverA
io.github.cyanheads
Resolve DOIs, search ~188M scholarly works, and fetch references via the Crossref REST API.
Research & Data Open Data
714
https://crossref.caseyjhand.com/mcp
Crossref Scholarly Data
io.github.Taru0208
Search 150M+ academic works, journals, and funders via Crossref API.
Search Research & Data Open Data
2
https://aligned-kettledrum--crossref-mcp-server.apify.actor/mcp
Evident Source CheckB
com.evidentagents
Check AI references against Crossref and DataCite. DOI/arXiv metadata checks, plus tool discovery.
E-commerce & Retail Product Management Customer Support
291
https://evidentagents.com/mcp
Research papersB
si.fourzerotwo
arXiv, PubMed, Crossref and OpenAlex scholarly metadata.
Research & Data Search Open Data
381
https://fourzerotwo.si/mcp/v/research

Related MCP Servers

Crossref MCP Server
Search Research & Data Open Data
JackKuo666
F
license
Not graded
quality
D
maintenance
Enables AI assistants to search academic literature and retrieve detailed metadata for papers, journals, and funding organizations via the Crossref database. It supports DOI-based lookups and keyword searches to facilitate programmatic access to scholarly research data.
Updated 2 years ago (2025-04-05 16:44 UTC)
7
-
crossref-mcp
Research & Data Search Open Data
ebiyu
A
license
A
quality
D
maintenance
Enables retrieval of academic literature metadata via DOI or search using the Crossref REST API.
Updated 3 months ago (2026-08-17 00:43 UTC)
2
MIT
mcp-crossref
Research & Data Open Data
pipeworx-io
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.
Updated 10 days ago (2026-10-31 08:33 UTC)
332 npm
MIT
Academic Paper Search MCP
Research & Data Search Education & Learning Tools
diegoli08
F
license
Not graded
quality
A
maintenance
Enables Claude and other MCP-compatible clients to query Semantic Scholar and Crossref for scholarly works, retrieving metadata, abstracts, TL;DR summaries, and full-text links when available.
Updated 25 days ago (2026-10-15 18:40 UTC)
-

crossref-mcp

Features

Quick start (local, stdio)

Configuration

Tools

Connecting an MCP client

Use as a skill (no server)

Docker / HTTP deployment

Public deployment (TLS / reverse proxy) — optional

Redis cache + cross-replica rate limiting — optional

CI / publishing

Install from the MCP registry

Security & trust

License

中文

特色

快速開始（本機 stdio）

設定

工具

連接 MCP client

當作 skill 使用（免 server）

Docker / HTTP 部署

公開部署（TLS / 反向代理）— 選用

Redis 快取 + 跨副本速率控制 — 選用

CI / 發佈

從 MCP registry 安裝

安全與信任

授權

Available Tools

Output Schema

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Crossref MCP Server

crossref-mcp

mcp-crossref

Academic Paper Search MCP