crossref-mcp

crossref-mcp

English | 中文

Crossref REST APIをラップしたMCPサーバーです。学術メタデータ（著作物、会員、ジャーナル、資金提供者、種類、ライセンス、プレフィックス）の検索機能を、LLM クライアントが呼び出せるツールとして提供します。

Crossref とは提携しておらず、Crossref の承認も受けていません。データは公開されている Crossref API からリアルタイムで提供されます。Crossref の ポライトプールに参加するには、CROSSREF_MAILTOを設定してください。

機能

• Crossref の主要なリソースエンドポイントを、18 個の読み取り専用ツールとして提供します。
• 2 種類のトランスポートに対応：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を再利用してください。すべてのツールはデフォルトで簡易フィールドを返します。Crossref の完全な JSON を取得するには、raw=trueを渡してください。

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 をご利用ください。エージェントに Crossref REST API を直接呼び出す方法を説明する、単体で利用できるスキルです。必要なのは HTTP／fetch 機能だけです（インストール、キー、コンテナは不要です）。その代わり、エージェントは MCP サーバーの丁寧なプールによるスロットリング、フィールドの簡略化、構造化されたエラー処理を利用せず、生の HTTP を送信して Crossref JSON を自分で解析します。

Claude Code（エージェントスキル）：

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 に配置してください。）

その他のエージェント（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 で X-API-Key を必須にするには、MCP_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 認証）とアプリケーション層の MCP_API_KEY を組み合わせます。どちらの場合も /health は公開されます。DNS がホストを指し、ポート 80／443 に到達できるドメインが必要です。Caddy のレート制限には caddy-ratelimit プラグインが必要です（カスタムビルド）。

Redis キャッシュ + レプリカ間のレート制限 — 任意

REDIS_URL を設定すると、レスポンスキャッシュ（未加工のエンベロープに対するキャッシュアサイド方式。キーから mailto／シークレットを除外）を利用できます。また、RATELIMIT_BACKEND=redis を設定すると、共有トークンバケットが有効になり、レプリカが Crossref の丁寧なプールのレート制限内に収まります。

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

Redis に障害が発生しても正常に縮退します（キャッシュなし、メモリ内のレート制限）。/health は redis: down の状態でも 200 を返します。

CI／公開

.github/workflows/ci.yml：test（すべての push／PR で ruff + format + 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 Access Token（Read/Write）。リリースタグを作成します（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 を使用してください。
• 丁寧なプール。 独自の 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）を、LLM クライアントが呼び出せるツールとして提供します。

Crossref の公式提供物ではなく、Crossref の承認も受けていません。データは公開されている Crossref API からリアルタイムで取得します。Crossref の 丁寧なプール に参加するには CROSSREF_MAILTO を設定してください。

特長

• Crossref の主要なリソースエンドポイントを扱う 読み取り専用ツール 18 個。
• 2 種類のトランスポート：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 で使用するメールアドレスです。
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.md が自己完結型のスキルとして、 エージェントが Crossref REST API を直接呼び出す 方法を説明します。必要なのはエージェントの HTTP/fetch 機能だけです（インストール不要、キー不要、コンテナ不要）。 代わりに、エージェント自身が raw 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 に配置します。）

その他のエージェント（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 が必要です（自分で build します）。

Redis キャッシュ + レプリカ間のレート制御 — 任意

REDIS_URL を設定すると、レスポンスキャッシュ（元の envelope を cache-aside 方式で保存。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 のときに heyinnaneo/crossref-mcp へ multi-arch image を push）。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 無隸屬關係。