crossref-mcp

crossref-mcp

English | 中文

一个封装 Crossref REST API 的 MCP 服务，将学术元数据查询（作品、成员、期刊、资助方、类型、许可证、前缀）作为工具提供给大模型客户端调用。

与 Crossref 无关联，也未获其认可。数据由公开的 Crossref API 实时提供。设置 CROSSREF_MAILTO 即可加入 Crossref 的 礼貌池。

功能特性

• 提供所有主要 Crossref 资源端点，封装为 18 个只读工具。
• 双传输方式：stdio（本地）和 Streamable HTTP（容器）。
• 礼貌池（User-Agent + mailto），可选 Crossref Plus 令牌。
• 令牌桶限流（根据 X-Rate-Limit-* 标头自动调整），并通过指数退避遵守 Retry-After。
• 游标深度分页、字段 select、raw 或简化输出。
• 可选的 X-API-Key HTTP 身份验证（/health 除外），以及 /health 端点。
• 可选的 Redis 响应缓存和跨副本限流。
• 可选的 Caddy TLS 反向代理，用于公开部署。

快速开始（本地，stdio）

uv sync
export CROSSREF_MAILTO="[email protected]"   # recommended (polite pool)
uv run crossref-mcp                         # starts a stdio MCP server

使用 MCP Inspector 检查：uv run mcp dev src/crossref_mcp/server.py。

配置

环境变量	必需	默认值	说明
CROSSREF_MAILTO	建议	—	用于加入 Crossref 礼貌池的电子邮箱。
CROSSREF_PLUS_TOKEN	否	—	Crossref Plus API 令牌（作为标头发送）。
CROSSREF_BASE_URL	否	https://api.crossref.org	API 基础 URL。
CROSSREF_TIMEOUT	否	30	每个请求的超时时间（秒）。
MCP_TRANSPORT	否	stdio	stdio 或 http。
MCP_API_KEY	否	—	若已设置，HTTP 请求必须包含匹配的 X-API-Key 标头（/health 除外）。
LOG_LEVEL	否	INFO	日志级别（日志输出到 stderr）。
REDIS_URL	否	—	启用 Redis 缓存和共享限流（可选）。
CACHE_TTL	否	86400	缓存 TTL（秒）。
RATELIMIT_BACKEND	否	in-memory	in-memory 或 redis。

工具

作品 — search_works、get_work（按 DOI 查询）、get_work_references（最多 50 条）、get_work_quality（注册机构）。 成员 / 期刊 / 资助方 — search_members · get_member · get_member_works；search_journals · get_journal（ISSN）· get_journal_works；search_funders · get_funder · get_funder_works。 类型 / 许可证 / 前缀 — list_types · get_type；list_licenses； get_prefix。另有 ping。

共享参数。 搜索/列表工具接受 query（作品还支持 query_bibliographic / query_author / query_title）、filter（Crossref 的 key:value,… 语法）、sort + order、rows（≤1000）+ offset， 以及 select。深度分页：设置 cursor="*"，然后重复使用返回的 next_cursor。所有工具默认返回简化字段；传入 raw=true 可获取完整的 Crossref JSON。

连接 MCP 客户端

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

{
  "mcpServers": {
    "crossref": {
      "command": "uvx",
      "args": ["crossref-mcp"],
      "env": { "CROSSREF_MAILTO": "[email protected]" }
    }
  }
}

或者通过 stdio 运行容器："command": "docker"、"args": ["run", "-i", "--rm", "-e", "CROSSREF_MAILTO", "heyinnaneo/crossref-mcp"]。

Streamable HTTP — 容器启动后，将支持 HTTP 的客户端指向 http://localhost:8000/mcp。如果设置了 MCP_API_KEY，请将其作为 X-API-Key 发送。

作为技能使用（无需服务）

不想运行服务？skill.md 是一份独立技能，教会 Agent 直接调用 Crossref REST API——只需具备 HTTP/fetch 能力（无需安装、密钥或容器）。代价是：Agent 需要直接发送原始 HTTP 请求并自行解析 Crossref JSON，无法使用 MCP 服务的 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

（也可以限定在项目范围内：将其放在代码库中的 .claude/skills/crossref-api/SKILL.md。）

**其他 Agent（Cursor、Claude Projects、自定义）：**将 skill.md 的内容粘贴到系统提示词／项目知识库／规则文件中。

Docker／HTTP 部署

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

在 /mcp 和 /health 提供 Streamable HTTP（compose 健康检查）。设置 MCP_API_KEY，即可要求访问 /mcp 时提供 X-API-Key。要在本地构建，请取消 docker-compose.yml 中 build: . 的注释。

公共部署（TLS／反向代理）——可选

将其置于捆绑的 Caddy 代理之后（Caddyfile + docker-compose.proxy.yml）：终止 TLS（自动使用 Let's Encrypt）、HTTP→HTTPS、SSE 流式传输，后端不发布到主机。

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

纵深防御：代理边缘（可选 IP 允许列表／Basic auth）+ MCP_API_KEY 应用层；两者都不限制 /health。需要一个 DNS 指向主机的域名，且端口 80/443 可访问。Caddy 限速需要 caddy-ratelimit 插件（自定义构建）。

Redis 缓存 + 跨副本限速——可选

设置 REDIS_URL 来启用响应缓存（对原始信封采用 cache-aside；mailto／密钥不会纳入缓存键）；再设置 RATELIMIT_BACKEND=redis，启用共享令牌桶，使各副本的请求速率保持在 Crossref polite-pool 的限制内。

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

Redis 故障时会优雅降级（不使用缓存，限速改用内存）；/health 仍返回 200，状态为 redis: down。

CI／发布

.github/workflows/ci.yml：test（每次推送／PR 都运行 ruff + 格式检查 + pytest 并生成覆盖率报告）、security（Trivy 文件系统扫描）、build-push（在 main／v* 标签上将多架构镜像推送到 heyinnaneo/crossref-mcp），以及打标签时运行的 publish-pypi（OIDC Trusted Publisher）+ publish-registry（MCP 注册表）。

代码库密钥（Settings → Secrets and variables → Actions）：DOCKERHUB_USERNAME = heyinnaneo，DOCKERHUB_TOKEN = Docker Hub 访问令牌（读取／写入）。为发布版本打标签（git tag v0.1.0 && git push origin v0.1.0）；标签必须与 pyproject.toml 一致。

从 MCP 注册表安装

已发布为 io.github.jtl-neo/crossref-mcp（参见 server.json），并提供 PyPI 软件包（uvx crossref-mcp）和 OCI 镜像。发布会在版本标签上自动进行（publish-pypi + publish-registry）；需要公开代码库和已配置的 PyPI Trusted Publisher。

安全与信任

• 只读。 每个工具都用于查询，并标注 readOnlyHint。
• 限速。 默认使用单进程内存限速——不要将其作为公共代理承载大量流量；对于副本，请使用 RATELIMIT_BACKEND=redis。
• Polite pool。 使用你自己的 CROSSREF_MAILTO。
• 公共 HTTP。 设置 MCP_API_KEY 并在前端配置 TLS。
• 不包含捆绑密钥。 .env 不会包含在镜像和 git 中。

许可证

MIT。书目数据来自公开的 Crossref REST API；与 Crossref 无关联。

---

中文

English | 中文

将 Crossref REST API 封装为 MCP 服务，把学术文献元数据查询（works、members、journals、funders、types、 licenses、prefixes）封装成大模型客户端可调用的工具。

非 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="[email protected]"   # 建議（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 客户端

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

{
  "mcpServers": {
    "crossref": {
      "command": "uvx",
      "args": ["crossref-mcp"],
      "env": { "CROSSREF_MAILTO": "[email protected]" }
    }
  }
}

或者使用容器运行 stdio："command": "docker"、"args": ["run", "-i", "--rm", "-e", "CROSSREF_MAILTO", "heyinnaneo/crossref-mcp"]。

Streamable HTTP — 容器启动后，将支持 HTTP 的客户端指向 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。要在本地构建，取消 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（自行构建）。

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