crossref-mcp

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.

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 無隸屬關係。