TCG MCP

tcg-mcp

Pokemon TCG MCP サーバーです。鑑定済みカードを検索し（現在はPSAに対応、CGC/BGSはスタブ）、所有カードのコレクションをローカルのSQLite DBで管理し、価格プロバイダー（Pokemon TCG APIとPriceCharting）に問い合わせ、目標価格を設定したウォッチリストを追跡し、PSAの鑑定枚数をスナップショットとして記録して、長期的な推移を確認できます。

tcg-mcpはModel Context Protocolサーバーです。一度インストールして、Claude Desktop／Claude Code／Cursor／その他のMCPクライアントに接続すると、アシスタントでPSAの鑑定番号データ、個人コレクション、リアルタイムの市場価格を扱う25個のツールを利用できます。

---

機能 — 名前空間ごとに25個のツール

PSA鑑定（tcg_psa_*） — 鑑定番号の検索、表裏の画像表示、鑑定枚数データのスナップショット記録と経時的な追跡に対応します。また、鑑定番号を検索し、1回の呼び出しで所有カードとして登録するワークフローツールもあります。

CGC／BGS（tcg_cgc_*、tcg_bgs_*） — v0.2ではスタブです。どちらの鑑定機関にも公開APIはありません。ルーティングの一貫性を保つために掲載しており、いずれかの鑑定機関がAPIを公開した場合は、適切にルーティングされます。

コレクション（tcg_collection_*） — 未鑑定または鑑定済みカード（ETB、ブースターボックス、UPC、缶などのシールド商品も含む）の追加、フィルターを使った一覧表示、取得原価の更新、ソフト削除（売却済みとしてマーク）または完全削除、価格リスティングへのカードの紐付け、取得原価の概要表示、または直近の価格スナップショットと照合したリアルタイムの市場評価額の取得ができます。

価格（tcg_pricing_*） — プロバイダーの検索、価格見積もりの取得（上位レベルの市場価格／最低価格／最高価格に加え、Pokemon TCG APIではバリアントごとの内訳、PriceChartingでは鑑定グレードごとの価格）、ローカルDBへのスナップショット保存、プロバイダーごとのレート制限を考慮した、紐付け済みカードすべての一括スナップショット取得、トレンド分析のための時系列データとしての過去スナップショットの照会ができます。

ウォッチリスト（tcg_watchlist_*） — 根拠となるメモを添えて購入目標価格を追加し、期間（flip／hold／sealed）で一覧表示し、更新し、理由（bought／thesis_invalidated／manual）を指定して終了できます。

メタ（tcg_list_providers） — 有効な鑑定・価格プロバイダー、各プロバイダーに必要な環境変数、各名前空間に含まれるツールを表示する検出ツールです。

すべてのツール一覧を確認するには、インストール後にtcg_list_providersを実行するか、アーキテクチャドキュメントをお読みください。

---

前提条件

1. Python 3.10以降（3.13を推奨）。
2. MCPクライアント — Claude Desktop、Claude Code、Cursor、Continueなど。
3. (任意、PSAツールのみ) PSA Public APIトークン — 無料です。psacard.com/publicapiで登録してください。

トークンがなくてもサーバーは動作します。Pokemon TCG APIの照会、コレクション、ウォッチリストの各ツールは、認証情報がまったくない初回インストール時からすべて利用できます。

---

インストール

オプションA — uvx（推奨、インストール不要）

# install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# run the server (auto-installs the package on first use)
uvx tcg-mcp --help

オプションB — pipx

pipx install tcg-mcp
tcg-mcp --help

オプションC — pip

python3 -m pip install tcg-mcp

オプションD — ソースから（コントリビューター向け）

git clone https://github.com/seanlok/tcg-mcp.git
cd tcg-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest        # run the test suite

---

設定

.env.exampleを.envにコピーし、利用するトークンを入力します。

cp .env.example .env
$EDITOR .env

または、クライアントでサポートされている方法で環境変数を設定してください（多くのクライアントでは、設定内の各MCPサーバーに対してenvを指定できます）。

環境変数	必要な機能	備考
PSA_API_TOKEN	PSAツール	こちらから取得 — 無料
POKEMONTCG_API_KEY	Pokemon TCG APIのレート制限緩和（任意）	こちらから取得 — 無料
PRICECHARTING_TOKEN	PriceChartingツール	有料サブスクリプションが必要
TCG_DB_PATH	ローカルDBの場所	デフォルトは~/.tcg-mcp/tcg.db

MCP クライアントに接続する

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、 %APPDATA%\Claude\claude_desktop_config.json（Windows）、または ~/.config/Claude/claude_desktop_config.json（Linux）を編集します。

{
  "mcpServers": {
    "tcg-mcp": {
      "command": "uvx",
      "args": ["tcg-mcp"],
      "env": {
        "PSA_API_TOKEN": "your-token-here",
        "TCG_DB_PATH": "~/Documents/tcg-mcp.db"
      }
    }
  }
}

Claude Desktop を完全に終了し（macOS では ⌘Q を押します。ウィンドウを閉じるだけでは不十分です）、再起動します。

Claude Code

claude mcp add tcg-mcp -- uvx tcg-mcp

次に、claude を実行するシェルでトークンをエクスポートします。

Cursor / Continue / など

同じ形式で、クライアントの接続先を次のように設定します。

command: uvx
args:    ["tcg-mcp"]
env:     PSA_API_TOKEN=...    # optional

---

動作確認

クライアントを接続したら、次のように尋ねてください。

「tcg-mcp を使って、プロバイダーを一覧表示してください。」

pokemontcg が有効になり、トークンを設定している場合は psa も有効になり、その他はスタブとして表示されます。

次に、実際に検索してみましょう。

「Pokemon TCG API で、Obsidian Flames の Charizard ex を検索してください。」

「1999 Pokemon Base Set Charizard #4（未鑑定）を、2026-04-15 に $250 で購入したものとしてコレクションに追加してください。」

「Charizard ex Surging Sparks を、目標購入価格 $180 でウォッチリストに追加してください。」

「コレクションの取得原価はいくらですか？」

---

アーキテクチャの概要

+----------------------+
|     MCP client       |  Claude Desktop, Cursor, etc.
+----------+-----------+
           | stdio (JSON-RPC)
+----------v-----------+
|     server.py        |  FastMCP — tool registration, validation
+----------+-----------+
           |
   +-------+-------+----------------+
   |               |                |
+--v--+         +--v--+        +----v----+
| psa |  ...    |pricing|      | storage |  SQLite — collection,
+--+--+         +--+----+      +----+----+  watchlist, pop trends,
   | httpx         | httpx          |       pricing snapshots
+--v---------------v----+      +----v----+
|  PSA / Pokemon TCG    |      | tcg.db  |
|  API / PriceCharting  |      +---------+
+-----------------------+

プロバイダーの抽象化（providers/base.py、 pricing/base.py）により、新しい鑑定会社や価格情報ソースの追加は、単一ファイルの変更で済みます。 docs/adding-a-provider.mdを参照してください。

---

ローカル SQLite データベース

コレクション、ウォッチリスト、価格スナップショット、ポップスナップショットなど、個人データはすべて単一の SQLite ファイルに保存されます。デフォルトの保存場所は ~/.tcg-mcp/tcg.dbです。TCG_DB_PATHを任意のパスに設定してください。

ファイル形式は通常の SQLite なので、データを直接確認したりバックアップしたりできます。

sqlite3 ~/.tcg-mcp/tcg.db
.tables
SELECT subject, grade, acquisition_price FROM owned_cards WHERE status='owned';

スキーマはsrc/tcg_mcp/storage/schema.sqlにあります。 マイグレーションは前方のみで、冪等性があります（起動のたびに実行しても安全です）。

---

既知の制限

• PSA の画像があるのは、2021 年 10 月以降に鑑定されたカードのみです。それ以前のスラブでは画像リストが空になります。これは上流 API の仕様であり、バグではありません。
• PSA の Brand フィールドは、スキーマ内で明確な「セット名」に最も近い項目です。これを set_name として公開しています。より詳細なセットの解析が必要な場合は、生のペイロードを参照してください。
• CGC / BGSプロバイダーは v0.2 ではスタブです。検出用に一覧表示されますが、呼び出すと NotSupportedError が発生します。実装には、いずれかの鑑定会社が公開 API を提供するか、節度あるスクレイピングを明示的にサポートする判断が必要です。
• PSA の無料プランのレート制限は公開されていません。「PSA API rate limit exceeded」と表示された場合は、時間をおくかプランをアップグレードしてください。
• PriceChartingは有料のみです。PRICECHARTING_TOKENがない場合、プロバイダーはdisabledとして登録され、鑑定済みカードの価格は利用できません。ただし、Pokemon TCG API では未鑑定カードの市場価格を取得できます。

---

ロードマップ

**継続的な制約：**以下の各マイルストーンでは、無料で利用できる方法をデフォルトとします。GemRate、eBay Marketplace Insights などの有料プロバイダーは、キーが設定されている場合にのみ有効になるオプションの追加機能として扱います。

• ✅ v0.3 — リリース済み： tcg_pricing_snapshot_collection、 tcg_pricing_get_history、アイテムごとの評価額の丸め、PSA 429 エラーメッセージの明確化、CHANGELOG.md。
• ✅ v0.4 — リリース済み： Pokemon TCG API を利用したカタログツール（tcg_catalog_*）、ウォッチリストとの共通部分を含むtcg_collection_set_completion、機能強化されたtcg_collection_search、スマートルーティング対応のtcg_pricing_get_card。
• v0.5 — CGC のサポート（無料の方法：節度あるスクレイピング。有料の GemRate はオプション）。
• v0.6 — BGS のサポート（無料の方法：節度あるスクレイピング。有料の GemRate はオプション）。
• v0.7 — eBay の落札価格比較（無料の方法：eBay Browse API とスクレイピング。有料の Marketplace Insights API はオプション）。

全バージョン履歴はCHANGELOG.mdを参照してください。

---

コントリビューション

コントリビューションを歓迎します。新しい鑑定または価格情報プロバイダーを追加する場合は、docs/adding-a-provider.mdを参照してください。実装要件は意図的にシンプルにしてあります。Protocol メソッドを実装し、認証情報に応じて登録し、mock-httpx テストを作成してください。

# Run tests + lint locally
pytest
ruff check .

---

免責事項

このプロジェクトは独立したものです。PSA、CGC、Beckett、The Pokemon Company、Nintendo、TCGPlayer、Cardmarket、PriceCharting、その他の組織とは提携していません。外部 API の呼び出しには、それぞれのプロバイダーの利用規約が適用されます。

---

ライセンス

MIT — LICENSE を参照してください。

---

参考情報

• Model Context Protocol — 公式サイト
• MCP Registry — 検索
• Pokemon TCG API — 価格情報＋カタログ
• PSA Public API
• PriceCharting API