Pokémon TCG API

@pokemontcgapi/mcp

pokemontcgapi.com の Pokémon TCG API 用 MCP サーバーです。カタログ全体を対象とした11個のツールをエージェントに提供します。国際版、日本語版、簡体字中国語版の印刷ライン、8つのロケールでのカード名、イラストレーター、画像、そして情報源、基準、グレード、サンプル数を含む価格情報に対応しています。現在の件数は /v1/status でリアルタイムに確認でき、内訳は coverage.json に掲載されています。

非公式です。Nintendo、Creatures Inc.、GAME FREAK inc.、The Pokémon Company International によって制作、承認、サポートされておらず、これらの企業との提携もありません。Pokémon および関連するすべての商標は、それぞれの所有者に帰属します。

キーを取得する

登録ごとに Idempotency-Key を一度生成し、リクエスト本文と一緒に保管してください。

IDEM=$(uuidgen)

curl -s -X POST "https://api.pokemontcgapi.com/v1/accounts/free" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"email":"[email protected]"}'

応答を紛失した場合は、24時間以内にまったく同じリクエスト（同じ Idempotency-Key、バイト単位で同一の本文、同じネットワーク：同じパブリック IPv4 または同じ IPv6 /64）を再送してください。保存されていれば、シークレットを含む応答が返されます。これは元の応答であるため、その後にローテーションまたは失効したキーが復活することはありません。同じメールアドレスで新しい Idempotency-Key を使うと 409 ACCOUNT_EXISTS が返されます。同じキーで異なる本文を送ると 409 IDEMPOTENCY_CONFLICT が返されます。

キーのハッシュのみを保存します。同じリクエストを再送できるよう、登録時の応答は24時間保持されます。今すぐ data.key.secret を保存してください。

再送できない場合は、サインインしてキーをローテーションするか、確認済みのメールアドレスを使って /v1/accounts/recover にアクセスし、新しいシークレットを取得してください。

キーは data.key.secret に返されます。メールで届くアドレス確認を完了すると、トライアルのクレジットは80から800に増え、登録から30日後に終了します。有料プランは月額29 EURからです： 料金。

インストール

Claude Code：

claude mcp add pokemontcgapi --env PTCG_API_KEY=your-key -- npx -y @pokemontcgapi/mcp

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "your-key" }
    }
  }
}

Cursor — .cursor/mcp.json：

{
  "mcpServers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "${env:PTCG_API_KEY}" }
    }
  }
}

VS Code — .vscode/mcp.json。トップレベルのキーは mcpServers ではなく servers です。また、inputs を使うとキーをコミット対象のファイルに含めずに済みます：

{
  "inputs": [
    { "id": "ptcg-key", "type": "promptString", "description": "pokemontcgapi key", "password": true }
  ],
  "servers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "${input:ptcg-key}" }
    }
  }
}

環境変数：11個のツールのうち10個で必要な PTCG_API_KEY と、PTCG_BASE_URL（既定値は https://api.pokemontcgapi.com）です。Node ≥ 20 が必要です。例外は公開ルートを読み取る ptcg_get_reference です。ptcg_get_catalogue_status は例外ではありません。公開 /v1/status から開始した後、印刷地域ごとに1セットを読み取るため、キーが必要です。キーがなくてもサーバーは起動してツールを一覧表示しますが、これら10個の呼び出しではキーを求められます。

ツール

エンドポイントごとに1つではなく、ツールは11個です。tools/list は毎ターン、モデルのコンテキストに含まれるため、ツール全体のサイズは約11 KBです。また、各ツールはルートではなく質問のような形になっているため、1つの質問に答えるために4回の呼び出しを連鎖させる必要はありません。

ツール	回答する内容
ptcg_search_cards	「日本のセットに収録されているリザードンのカード」。名前、セット、地域、レアリティ、アーティスト、発売時期で検索できます
ptcg_get_cards	1回の呼び出しで最大100個のIDを取得します。base1-4 と bs-4 はどちらも解決されます
ptcg_get_card_prices	カードの現在の観測値をすべて取得します。版、グレード、as_of、sample_n を含みます
ptcg_list_sets	「2024年に発売された日本のセットをすべて」
ptcg_get_reference	タイプ、スーパータイプ、レアリティの正確な文字列を取得できるため、フィルターを推測する必要がありません
ptcg_list_artists	イラストレーターと、それぞれが描いたカードの枚数
ptcg_get_catalogue_status	カタログに含まれるものと含まれないものを、リアルタイムで確認できます
ptcg_measure_centering	カードの片面の写真から、比率、不確実性、幾何情報を取得します。25クレジット。上限値がない状態で要確認となるのは想定内です
ptcg_grade_centering	既知の面比率／軸比率に基づく、センタリングのみの上限値です。1クレジット
ptcg_get_centering_standards	PSA/BGS/CGC/SGC の基準値、情報源の状態、URLです。1クレジット
ptcg_identify_card_from_image	「これはどのカードの写真ですか？」 — 候補を順位付けして返します。再版で同じアートワークが使われている場合は、明示的に特定を拒否します。1回の呼び出しにつき25クレジット。Growth プラン以上では利用料金に含まれます

すべてのツールには readOnlyHint: true と destructiveHint: false が注釈として付与されています。ここで書き込みが行われることはありません。 ptcg_identify_card_from_image と3つのセンタリングツールには idempotentHint: false が設定されています。 呼び出すたびにクレジットを消費します。有料の処理を自動的に再試行しないでください。

センタリングは Growth 以上のプランに含まれます。Developer プランでは利用できません。認証済みの Free トライアルでは、測定を5回、確認を5回、それぞれ利用できます。グレードと基準値には、個別のトライアル呼び出し上限はありません。 測定では、base64 画像データ、明示的な表面／裏面、任意の standard／small のカードサイズ、および補正済みの角（EXIF の向きに合わせたピクセル座標で、左上、右上、右下、左下の順。長辺が2560 px以下になるよう縮小）を指定できます。 比率、不確実性、編集可能な幾何情報が返されます。上限値が null のまま要確認となるのは想定内です。 別の測定で角を補正した後、アプリで担当者が裁断線と印刷線を確認または移動します。アプリが confirm を呼び出すとグレードの上限値が返されるほか、既知の比率から grade を通じて取得することもできます。

意図的にconfirm ツールはありません。アシスタントは、担当者が線を確認したと断言できません。担当者から明示的な承認を受け取るアプリだけが、confirmed_by: person を送信できます。 必ずセンタリングのみに基づく上限値であり、最終グレードの予測ではないことを表示してください。結果を検証済みまたは認定済みと表示しないでください。情報源の状態、不完全であることを示すフラグ、不確実性は常に表示してください。 2段階のガイドをご覧ください。

商用利用に関する拒否では、ツールの結果の1行目に next_step.handoff が記載され、その後に API メッセージと詳細情報がすべて続きます。その文と URL をアカウント所有者に一字一句そのまま提示し、再試行しないでください。所有者が購入手続き、メール認証、または問い合わせの手順を完了します。CARD_ALLOWANCE_EXCEEDED もその一例です。該当期間における固有カードの取得上限（トライアルでは1,000件、Developer では月30,000件）に達しています。取得済みのカードは引き続き回答に使用できますが、新しいカードを取得するには次の期間まで待つか、Growth にアップグレードする必要があります。

カードカタログのインポート

カードをすべてインポートするには、REST APIを直接使用します。 GET /v1/cards?limit=250&orderBy=idを呼び出し、links.nextをそのまま次のリクエストに使用してください。フラットな一覧はセットの境界をまたいでページ分割されるため、セットごとにカードを取得するよりリクエスト数を抑えられます。 通常のカタログ料金のまま名前も取得するには、include=translationsを追加します。料金が設定されているインクルード項目には、それぞれ別の料金が適用されます。 単一の印刷地域に絞り込むには、q=set.region:JPまたはq=set.region:CNを追加します。langは名前の翻訳を選択するだけです。 特定のセットが必要な場合は/v1/sets/{code}/cardsを、セットのメタデータを参照する場合は/v1/sets?region=JPを使用してください。

クイックスタートには、ページ分割のループと日付付きの測定結果が記載されています。 移行ガイドでは、インポート前に変更フィードのウォーターマークを取得し、その後レプリカを維持する方法を説明しています。 MCP検索ツールは、範囲を限定した対話型検索を目的としています。region引数はset.region:JP（またはCN、WEST）としてAPIに送信されるため、日本語での検索では日本語の行のみが取得されます。すべてをインポートする場合はRESTを使用してください。

このAPIにないもの

最後のツールはこのセクションの内容を扱うためのもので、モデルに推測させるのではなく、ライブ呼び出しでこれらの事実を返します。

• 韓国語のカードはありません。 KRのセットは0件で、koの翻訳も0件です。印刷地域とロケールはスキーマでモデル化されていますが、データはないため、これらで絞り込むとエラーではなく空の結果が返されます。
• カードゲームのテキストは英語で、データにはばらつきがあります。 attacks、abilities、weaknesses、resistances、subtypes、retreat_cost、rules、flavor_textには、2026年9月3日以降のデータが、20,725枚の西洋版カードに登録されています。57,450枚のカードを対象に2026年9月16日に測定したところ、全カタログにおけるattacksの割合は29.9％、西洋版の割合は82.9％でした。また、subtypesは35.0％、weaknessesは28.0％、flavor_textは17.9％、abilitiesは7.0％、rulesは5.1％でした。日本語版と中国語版にはこれらのデータがないため、attacksがnullでも、カードに攻撃がないという意味ではなく、データを保持していないことを示します。
• フォーマットの合法性情報はありません。 カードオブジェクトにはlegalitiesフィールドがなく、levelも空です。デッキの合法性に関する質問には、このAPIでは回答できません。

この3点はすべて測定され、ソース内に日付とともに記載されており、ツールの説明にも一字一句そのまま記載されているため、エージェントは呼び出し後ではなく、呼び出す前に把握できます。

価格を正しく読み取る

印刷版のフィルターはありません。1st Edition、Unlimited、ホロ、リバースホロ、グレーディング済みの行はすべて一緒に返されるため、最初の価格を選ぶのではなく、各行の printing、condition、grading を確認してください。basis は、上流で公開された GUIDE と、当社が計算した DERIVED を区別します。PTCG_INDEX は当社独自の複合指標で、通貨は EUR、sample_n も含まれます。すべての観測値には as_of 日付があり、少なくとも1日遅れているため、日付を付けずに価格を提示しないでください。

プランによって非公開になる項目は明示されており、隠されているわけではありません。トライアルキーでは graded と non_english_locales、Developer では graded が非公開になり、Growth 以上では非公開項目はありません。API は価格ルートの meta.withheld、カードに価格が含まれる場合の X-Plan-Withheld ヘッダー、バッチのトップレベルにある withheld フィールドでこれを示します。そのため、カードにグレーディング済みの行がない場合、それはカタログではなくプランによる制限かもしれません。

ptcg_get_cards では、API の missing フィールドが存在する場合、それが正式な情報源となります。suggested_id の値も含まれます。ツールは既存の文字列配列 missing を維持し、新たに { id, suggested_id? } の配列である missing_details を追加します。テキストにも各候補が表示されます。API に missing がない場合、ツールは要求した ID と返された id および legacy_id を比較し、大文字と小文字の違いと重複 ID を無視します。これにより、追加のリクエストを行わずに古い API バージョンにも対応できますが、報告されない正規セットの衝突や候補を検出することはできません。現行の API はすべての ID が解決されると missing を省略するため、その場合、このフォールバックは空の配列を返します。 ptcg_get_card_prices は価格とともにカードを読み込むため、除外項目はそのヘッダーで届きます。

コンテキストの管理

API で許可される件数にかかわらず、結果は最大50行に制限され、JSON ではなく、列を揃えたテーブルと簡潔なフィールド構成で返されます。同じ行数なら、各行でキーを繰り返さないテーブルのほうが JSON より短くなります。再現可能な測定値を併記できないため、割合は公表していません。 切り捨てが発生する場合は、続きのカーソルとともに必ず通知されます。価格の行だけは切り捨てられません。

プロトコル

@modelcontextprotocol/server v2 を基盤とし、 2025-11-25 リビジョンをネゴシエーションし、2024-10-07 までのクライアントを受け入れます。stdio トランスポートを使用します。

このリビジョンはライブラリのものであり、当社独自の主張ではありません。@modelcontextprotocol/[email protected] の SUPPORTED_PROTOCOL_VERSIONS は 2025-11-25 が最新のため、それより新しいバージョンを要求するクライアントには、そのバージョンで応答します。変更履歴ではなく、公開済みパッケージで検証しています。

こちらもご利用いただけます

• TypeScript SDK、ランタイム依存関係なし：@pokemontcgapi/sdk — ソース
• ドキュメント：https://pokemontcgapi.com/docs
• カバレッジ、ライブ測定値：https://pokemontcgapi.com/coverage

ソースからビルドする

npm ci
npm run typecheck
npm run build

Node >= 20。npm test は tests/ 内のユニットテストを実行します。CI で確認するのは、Node 20 と Node 22 の両方でパッケージの型チェックとビルドが成功すること、および npm pack がレジストリに公開される予定のファイル一覧を生成することです。

このパッケージは、pokemontcgapi.com を運営する非公開のモノレポ内で開発され、リリースごとにこちらへミラーリングされます。そのため、マージされたプルリクエストはマージボタンではなく、手作業で反映されます。 これはほかの場所にパッチを送るべきだという意味ではありません。こちらで issue または PR を作成してください。確認されるのはこちらです。

ライセンス

MIT。API が提供するデータには、ソースごとに再配布条件があります。https://pokemontcgapi.com/legal/attribution をご覧ください。