NeoSatoshi Card Recognition

NeoSatoshi Card Recognition MCP サーバー

NeoSatoshi card recognition API 用の MCP サーバーです。Claude、Cursor、Codex などの MCP クライアントで、写真に写ったポケモン、ONE PIECE、ディズニー・ロルカナ、遊☆戯☆王、Magic: The Gathering、Star Wars: Unlimited、デジモンカードゲーム、サッカー（フットボール）カードを識別できます（バインダーのページにも対応。サッカーカードは写真1枚につき1枚です）。カードのセット、番号、レアリティ、Cardmarket ID、日次価格を JSON で取得でき（サッカーの場合は選手、リリース、パラレル）、カードカタログを検索できます。

• トランスポート：stdio
• npm パッケージ：neosatoshi-card-mcp、バイナリ：neosatoshi-card-mcp
• Node.js 18 以降

ツール

recognize_cards

引数	型	説明
image_path	string	ローカルの .jpg、.jpeg、または .png。最大 12 MB（サッカーは 4 MB）。~ は展開されます。
image_url	string	JPEG または PNG の公開 https:// URL。API にそのまま転送され、サーバーがダウンロードすることはありません。
image_base64	string	Base64 形式の JPEG または PNG。data:image/...;base64, プレフィックスも使用できます。
tcg	enum	pokemon（デフォルト）、onepiece、lorcana、yugioh、magic、star_wars_unlimited、digimon、football

| include_images | boolean | 認識したカードのうち最大10枚について、カタログ画像も返します（当社の CDN から取得。合計最大 4 MB）。アシスタントが写真と比較するために使えます。デフォルトは false です。 |

image_path、image_url、image_base64 のいずれか1つだけを指定してください。結果にはカードごとの短いテキスト要約、API レスポンス全体をテキスト化した JSON、および同じレスポンスの structuredContent が含まれます。API エラーは、API の error コードと message を含むツールエラーとして返されます。

要約行の例：

1. Cinderace ex | Scarlet & Violet Black Star Promos (PR-SV) #163 | Promo | en | Cardmarket 796939 | trend 3.59 EUR | confidence 0.85 | 5 alternatives

デジモンの行（別イラストはカード番号を共有します。セットの後に印刷 ID とそのバリアントが続きます）：

1. WarGreymon | RELEASE SPECIAL BOOSTER Ver.1.0 [BT01-03] (BT1) #BT1-025 | BT1-025_P1 Alternative Art | SR | en | Cardmarket 620026 | trend 16.85 EUR | TCGplayer 9.54 USD | confidence 1

デジモンカードゲーム（digimon）、英語版および日本語版：カード番号とカード名で認識されます。画像から別イラストを判別できない場合、print_unconfirmed は true になり、card_id は dg-c-<number>（価格なし）になります。印刷版は候補としてそれぞれの価格とともに返されるため、correct_card で選択できます。英語版と日本語版の印刷版には Cardmarket 価格（EUR）、英語版のみ TCGplayer 価格（USD）が表示されます。古いデジモン製品（1999年のカードゲーム、2000年のトレーディングカード）は認識されません。

サッカーの行（価格はまだありません。パラレルは候補として提示され、ユーザーによる確認が必要です）：

1. Niklas Beste | 2025-26 Topps Chrome Bundesliga #BA-NBE | Base Cards Autograph Variation | Sport-Club Freiburg | parallel Gold Wave Refractor /50 (suggested, confirm it) | serial 37 | 2 alternatives | no price yet

クライアントが進行状況トークンを送信すると（Claude Code、Claude Desktop、およびほとんどのクライアントが送信します）、検出結果はストリーミングされ、カードが認識されるたびに報告されます。ロルカナのカードが8枚写ったページでは、最初のカードは約8秒後、8枚すべては11秒後に報告されました。

API はカードを識別しますが、状態のグレーディングは行いません（PSA、BGS、CGC のスラブは、サッカーの場合は SGC のスラブも、ラベルから読み取ったグレードを返します）。カード1枚の処理には通常約4秒、しばらくリクエストがなかった後の最初のリクエストでは約10～12秒かかります。カードが9枚のバインダーページは約17秒、サッカーカードは約6～25秒です。クライアントの待機時間は最大120秒です。

recognize_folder

Argument	Type	Description
folder	string	写真が保存されているローカルフォルダー（サブフォルダーは対象外）。~ は展開されます。
tcg	enum	フォルダーごとにゲームを1つ指定します。デフォルトは pokemon です。
max_files	integer	名前順で処理する写真の最大数です。デフォルトは20、上限は100です。
output	enum	csv（デフォルト）、json（API形式）、または both を指定します。フォルダー内に新しいファイルとして書き出されます。

写真ごとに1回検出し、検出されたカードごとに1クレジットを消費します。既存のファイルが上書きされることはありません。すべての写真で失敗するエラー（クレジット不足、無効なキー、デモの上限）を検出すると、処理を早期に停止します。CSVの列：file、card_index、name、tcg、language、set_name、set_code、number、rarity、cardmarket_id、cardmarket_trend_eur、cardmarket_avg30_eur、tcgplayer_market_usd、confidence、graded、season、subset、parallel、request_id。表計算ソフトで実行されないよう、=、+、-、@ で始まるセルには先頭に ' が追加されます。

search_cards

カードカタログを検索します。結果は検出結果と同様の完全なカードオブジェクト（セット、番号、レアリティ、Cardmarket の商品ID、日次価格、画像）で、最大10件です。has_more は含まれますが、総件数は含まれません。recognize_cards の request_id と card_index を指定すると、無料の修正検索になります（検出されたカード1枚につき24時間以内に5回、最大5件の結果）。これらを指定しない場合は有料のカード検索となり、カードが返されたときに0.5クレジットを消費します。

フットボール：{"tcg": "football", "q": "kane chrome 2023"} のように指定します。指定できるのは q のみです（選手名と、任意でセット名またはシーズンを表す語句）。language、set、number は指定できず、価格情報もまだありません。各結果には get_card 用の ref が含まれます。

correct_card

検出されたカードを正しいカタログカードに修正します（修正検索またはカードの候補から取得した card_id を指定）。無料で、検出から24時間以内にカード1枚につき3回まで、検出に使用したキーからのみ利用できます。

get_card

card_id を指定してカードを1枚取得します。価格の更新などに使用します。カードが存在する場合、0.5クレジットを消費します。検出結果が誤っている場合は、代わりに request_id を指定して search_cards を実行し、correct_card で修正してください。どちらも無料です。

フットボール：search_cards の結果から取得した ref を渡します（同じキーで24時間以内）。カードには、サブセットのすべてのパラレルとその発行枚数が含まれます。有効な ref がない場合、呼び出しは拒否され、料金はかかりません。

export_cards

最大20件の検出（recognize_cards または recognize_folder の request_ids。48時間以内）を、NeoSatoshi のウェブサイトがエクスポートするものと同じファイルとして出力します。ウェブサイト独自のエクスポートコードで生成されるため、新しいカードに適用した条件、correct_card による修正、保存済みプリセット、価格ルール、テンプレートが反映されます。

• format に csv／json（デフォルトは csv）を指定：カスタムエクスポートです。preset（保存済みプリセットID）、または fields と json_mode（api = ドキュメントに記載されたカード形式、custom = 指定したフィールド）を使用します。
• format に tcgpowertools を指定：Cardmarket 用の TCGPowerTools CSV です（TCGPowerTools のルールと保存済みコメントを使用。コメントは comment）。
• format に shopify を指定：Shopify の商品CSVです。価格はストアの通貨で出力されます（store_currency。指定がない場合は接続済みのストアから読み取ります。variant_mode）。
• format に ebay を指定：1つのサイト向けの eBay Seller Hub CSV です（marketplace。例：EBAY_DE。one_row_per_card）。
• 最後の3形式では、ウェブサイトの価格設定ステップにあるボタンと同様に、price_source、min_price、markup_percent、rounding を指定できます（マークアップまたは丸めを指定すると保存済みの価格ルールが置き換えられます。markup_percent が0の場合はマークアップなし）。save_to_folder を指定すると、許可されたフォルダーに新しいファイルを書き込みます（上書きはしません）。指定しない場合、ファイルは回答に含まれます（最大100 KB）。無料で、本人のキーでのみ利用できます（デモの検出結果にはカードが保存されません）。フットボールにはまだ対応していません。回答には、出力対象から除外されたカード（skipped）と、価格が特殊バージョンに依存するカード（warnings）が示されます。

list_export_presets

保存済みのエクスポートプリセット（組み込みの推奨CSVを含む）と、export_cards で指定できるすべてのフィールドIDを返します。無料です。

list_supported_games

ゲーム、カードの言語、tcg の値、上限、カード検索の料金を返します。API呼び出しは発生せず、料金もかかりません。

コスト

呼び出し	自分のキー	デモキー
recognize_cards	検出されたカード1枚につき1クレジット。カードがなければ無料	ネットワークごとに1日10回
search_cards（カード検索）、get_card	カードが返された場合に0.5クレジット	ネットワークごとに1日10回の検索、3回の照会。料金はかかりません
search_cards（request_id を指定）、correct_card	無料	無料
export_cards、list_export_presets	無料。1日200回までエクスポート可能	利用不可（デモで検出したカードは保存されません）

設定

変数	必須	説明
NEOSATOSHI_API_KEY	いいえ	https://neosatoshi.com/dashboard/settings/settings#api-keys で取得した API キー（有料プラン）。設定しない場合は、公開デモキーが使用されます。ネットワークごとに1日10回まで検出できます。
NEOSATOSHI_ALLOWED_DIRS	いいえ	image_path から読み取り可能なディレクトリ。区切り文字は :（Windows では ;）です。未設定の場合は、読み取り可能なすべての画像ファイルが対象になります。アシスタントが送信できるファイルを制限するには、この値を設定してください。

セットアップ

Claude Code

claude mcp add neosatoshi-cards -e NEOSATOSHI_API_KEY=your_key -- npx -y neosatoshi-card-mcp

ディレクトリを制限する場合：

claude mcp add neosatoshi-cards -e NEOSATOSHI_API_KEY=your_key -e NEOSATOSHI_ALLOWED_DIRS="$HOME/Pictures/cards" -- npx -y neosatoshi-card-mcp

デモキーで試す場合は、-e NEOSATOSHI_API_KEY=... を省略してください。

Claude Desktop（ワンクリック）

neosatoshi-card-mcp.mcpb をダウンロードして開きます。Claude Desktop が拡張機能をインストールし、任意の API キーと任意の許可フォルダーを尋ねます。Node.js は Claude Desktop に付属しています。

npm run build:mcpb で自分でビルドできます（dev dependencies が必要です）。

Claude Desktop（手動）

claude_desktop_config.json に追加します（macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "neosatoshi-cards": {
      "command": "npx",
      "args": ["-y", "neosatoshi-card-mcp"],
      "env": {
        "NEOSATOSHI_API_KEY": "your_key",
        "NEOSATOSHI_ALLOWED_DIRS": "/Users/you/Pictures/cards"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）：

{
  "mcpServers": {
    "neosatoshi-cards": {
      "command": "npx",
      "args": ["-y", "neosatoshi-card-mcp"],
      "env": { "NEOSATOSHI_API_KEY": "your_key" }
    }
  }
}

Codex CLI

~/.codex/config.toml：

[mcp_servers.neosatoshi-cards]
command = "npx"
args = ["-y", "neosatoshi-card-mcp"]
env = { NEOSATOSHI_API_KEY = "your_key" }

ソースから実行

cd mcp-server
npm install
npm run build
node dist/index.js   # speaks MCP on stdin/stdout

npx の代わりに、任意のクライアントで node /absolute/path/to/mcp-server/dist/index.js を指定してください。

セキュリティ

• ファイル：通常のファイルのみを読み取ります。ディレクトリ、デバイス、ソケット、パイプは拒否されます。シンボリックリンクは最初に解決され、実際の対象が検証されます。JPEG または PNG のマジックバイトで始まる内容の .jpg、.jpeg、.png のみを受け付けます。上限は12 MB（サッカーは4 MB）です。
• NEOSATOSHI_ALLOWED_DIRS は解決後の実際のパスに対して検証されるため、../ やシンボリックリンクを使って範囲外に出ることはできません。存在しない項目は何も許可しません。
• ネットワーク：サーバーが呼び出すのは https://europe-west1-neosatoshi.cloudfunctions.net/detectApi と .../cardsApi のみです。また、include_images を指定した場合は、カード画像 CDN の https://d1m1gwcombja0u.cloudfront.net も呼び出します（その他の画像ホストはスキップされます）。
• 書き込み：書き込みを行うのは recognize_folder のみで、読み取ったフォルダー内に新しいファイル neosatoshi_cards_<date>-<time>.csv / .json を作成する場合に限られます（同じ NEOSATOSHI_ALLOWED_DIRS の検証を行います）。image_url は API に渡され、API が取得して検証します。サーバー自体が URL を取得することはありません。
• シェルは実行しません。
• API キーが送信されるのは Authorization ヘッダーのみです。ログに記録されたり、返されたりすることはなく、エラーメッセージからも取り除かれます。

開発

npm install
npm test     # builds, then runs node:test (file safety and tool tests with a fake fetch, no live API calls)

公開に関する注意事項

• server.json は公式 MCP レジストリ（https://registry.modelcontextprotocol.io）用です。その name は package.json の mcpName（io.github.Cookiebreed/card-recognition-mcp）と一致します。レジストリでは io.github.* 名に対して GitHub の所有権が確認されます。
• smithery.yaml は Smithery 用です。
• mcpb/manifest.json と scripts/build-mcpb.mjs は Claude Desktop 拡張機能をビルドします。neosatoshi-card-mcp.mcpb を、各 GitHub リリースに必ずこの名前でアップロードしてください。

ライセンス

このコードは MIT ライセンスです（LICENSE を参照）。API は https://neosatoshi.com/termsofuse に準拠する商用サービスです。