Scryfall MCP Server

Scryfall MCP サーバー

Magic: The Gathering の検索、ルールの照会、価格確認、セットの検索、デッキ構築ワークフローに対応した、Scryfall を利用する MCP サーバーです。

現在、プロジェクトは以下をサポートしています。

• ローカル MCP クライアント向けの主要トランスポートとして stdio
• src/http.ts を介したローカル優先の Streamable HTTP
• 15 個の MCP ツール、3 個のリソース、2 個のプロンプト

公開している機能

ツール

• search_cards：ページ指定、並べ替え、任意の価格フィルターを使って Scryfall のカード検索を実行します。
• get_card：名前、セット／コレクター番号、または Scryfall ID を使ってカードを 1 枚取得します。
• get_card_prices：任意のフォーマット情報と代替カードを含む価格データを返します。
• random_card：任意のフィルターを指定してランダムなカードを取得します。
• search_sets：Magic のセットを検索して絞り込みます。
• query_rules：ローカルの総合ルールファイルを、前後の文脈とともに検索します。
• build_scryfall_query：自然言語を、説明可能な Scryfall クエリに変換します。
• search_format_staples：公開されている価格と並べ替えのヒューリスティックを使って、フォーマットで使用可能な候補を検索します。大会のメタゲームデータは使用しません。
• search_alternatives：公開されている価格、タイプ、マナ総量のヒューリスティックを使って候補を検索します。結果は、機能的な代替カードや上位互換であることが検証されていません。
• find_synergistic_cards：カード、テーマ、またはアーキタイプに合うシナジーカードを検索します。
• batch_card_analysis：複数のカードについて、使用可能性、価格、シナジー、または構成を分析します。
• validate_brawl_commander：Brawl および Standard Brawl の統率者として使用可能か確認します。
• analyze_deck_composition：デッキリストのマナカーブ、色、構成上の問題を評価します。
• suggest_mana_base：色の要件に基づき、土地の枚数と色マナを整えるパッケージを提案します。
• show_card_search：Scryfall のカード検索結果を視覚的に表示する ChatGPT Apps ウィジェットを描画します。

リソース

• card-database://bulk：キャッシュされた Oracle 一括スナップショット。
• set-database://all：キャッシュされたセット一覧のスナップショット。
• ui://widget/card-search.html：show_card_search 用の ChatGPT Apps ウィジェットテンプレート。

プロンプト

• analyze_card
• build_deck

トランスポート

STDIO

Claude Desktop、Codex、MCP Inspector、およびほとんどのローカル MCP クライアントに推奨されます。

npm run dev

npm start

Streamable HTTP

ローカル環境、または明示的に管理された環境向けに、別のエントリーポイントとして利用できます。

npm run dev:http

npm run start:http

ローカル MCP テストの場合：

npm run dev:http:local
npm run smoke:http

スモークテストでは /health を確認し、MCP の initialize を実行して notifications/initialized を送信し、tools/list を検証します。 また、代表的な validate_brawl_commander と search_cards のツール呼び出しも実行するため、ローカル HTTP エンドポイントを機能の検出だけでなく、その先まで確認できます。

HTTP リクエストには、デフォルトで 1 MiB の本文サイズ制限（HTTP_MAX_BODY_BYTES）が適用されます。SDK やツールによる検証の前に、HTTP エントリーポイントでは、リクエスト JSON に含まれる配列要素とオブジェクトキーの合計が 10,000 個を超える場合も拒否します。この制限はバッチを含むリクエスト全体に適用されます。また、SDK 1.32.2 ではバッチ内のメッセージ数も 100 件に制限されます。この構造ガードは反復処理で実装されており、このプロジェクトの低レベル Server ハンドラーに適用されます。オプトインの McpServer.maxToolInputElements オプションには依存しません。

現在の HTTP の動作：

• デフォルトでは 127.0.0.1 にバインドします
• /mcp で POST|GET|DELETE を提供します
• GET /health を提供します
• HTTP_ALLOWED_ORIGINS が設定されていない限り、デフォルトでループバック以外の Origin ヘッダーを拒否します
• HTTP_HOST がループバック以外の場合、HTTP_AUTH_TOKEN と HTTP_TRUST_PROXY_TLS=true の両方を必須とします。後者は、信頼できる HTTPS プロキシまたはトンネルによって、暗号化されていないリスナーが保護されていることを運用者が明示するものです
• HTTP_MAX_SESSIONS で、アクティブなセッションと初期化中のセッションを制限します（デフォルトは 100）

HTTP エントリーポイントは現在も有用ですが、ドキュメントでは引き続き慎重な表現をしています。ここでは、パブリックホスティングの仕組みとして紹介していません。

ChatGPT アプリの開発

HTTP MCP エンドポイントは、ローカルアプリのプロトタイプとして ChatGPT Developer Mode に接続できます。ループバックでサーバーを起動します。

npm run dev:http:local

HTTPS トンネルを使って、そのローカルエンドポイントを公開します。

ngrok http 3000

次に、トンネル経由の https://.../mcp URL を ChatGPT Developer Mode に接続します。ツールの記述子、ウィジェットのリソース、またはメタデータを変更した後は、アプリを更新して、ChatGPT に最新の MCP インターフェースを再読み込みさせてください。

現在 ChatGPT 向けのウィジェットは show_card_search です。モデル向けに簡潔な structuredContent を返し、ChatGPT では ui://widget/card-search.html をレンダリングします。このウィジェットは Scryfall に対して読み取り専用で、Scryfall の画像 URL を使用し、CSP リソースの許可リストを https://cards.scryfall.io のみにしています。

セットアップ

前提条件

• Node.js ^20.19.0、^22.13.0、または >=24.0.0
• npm

インストール

git clone https://github.com/bmurdock/scryfall-mcp.git
cd scryfall-mcp
npm install
cp .env.example .env

記載されている npm run dev*、npm start、および npm run inspector コマンドは、.env を事前に読み込みます。明示的に指定されたプロセス環境変数は、そのファイル内の値より優先されます。dist/index.js を直接起動する MCP クライアントでは、独自の env 設定を通じてオーバーライドを指定してください。

検証

npm run lint
npm run type-check
npm test
npm run test:coverage

ビルド

npm run build

よく使うコマンド

npm run dev
npm run dev:http
npm start
npm run start:http
npm test
npm run test:watch
npm run test:ui
npm run test:coverage
npm run lint
npm run lint:fix
npm run type-check
npm run inspector

設定

正規の値については .env.example を参照してください。現在使用中の主な変数は次のとおりです。

• SCRYFALL_USER_AGENT
• RATE_LIMIT_MS
• RATE_LIMIT_QUEUE_MAX
• SCRYFALL_TIMEOUT_MS
• CACHE_MAX_SIZE
• CACHE_MAX_MEMORY_MB
• LOG_LEVEL
• NODE_ENV
• HEALTHCHECK_DEEP
• HTTP_HOST
• HTTP_PORT
• HTTP_MCP_PATH
• HTTP_HEALTH_PATH
• HTTP_MAX_BODY_BYTES
• HTTP_SESSION_IDLE_MS
• HTTP_SESSION_CLEANUP_INTERVAL_MS
• HTTP_ALLOWED_ORIGINS
• HTTP_AUTH_TOKEN
• HTTP_TRUST_PROXY_TLS
• HTTP_MAX_SESSIONS

運用上の注意：

• Scryfall API 呼び出しは、共有レートリミッターによってグローバルに直列化されます。バッチツールは複数のローカル検索をスケジュールできますが、設計上、Scryfall へのリクエストは常に一度に 1 件ずつ完了します。
• デフォルトのリクエスト間隔は、一般的な API エンドポイントでは 100 ms、Scryfall の 2 リクエスト/秒のカードエンドポイント（/cards/search、/cards/named、/cards/random、/cards/collection）では 500 ms 以上です。
• HTTP 429 レスポンスは自動的に再試行されません。サーバーは Scryfall のスロットル期間を記録し、次のリクエストの開始を遅らせます。再試行するかどうかは呼び出し元が判断できます。
• CACHE_MAX_MEMORY_MB は、card-database://bulk を含む大容量のインメモリスナップショットを保持できるかどうかを制御します。バルクリソースの再構築はまず一時ファイルにストリーミングされます。サイズの大きいスナップショットはキャッシュに保持されず、ウォーム読み込み用にディスク上に残ります。各 MCP リソースレスポンスでは、リソースプロトコルに必要な完全なシリアル化済みバルクペイロードが引き続きメモリ上に展開されるため、呼び出し元はレスポンスサイズに比例するメモリを確保してください。
• セットのスナップショットは毎週更新されます。キャッシュ容量に応じて、古いスナップショットは最大 4 週間保持され、定期更新に失敗した場合はそれが提供されることがあります。定期更新に失敗した場合は、5 分後に再試行されます。
• カードの詳細出力には、利用可能な場合、Scryfall のソースリンクとアーティストのクレジットが含まれます。Scryfall の画像 URL を表示する利用者は、著作権、アーティスト、ソースの情報を保持してください。また、カード画像をトリミング、変形、色変更、透かし加工したり、所有権を主張したりしないでください。
• 英語以外の get_card 検索では、Scryfall のローカライズ版セット／コレクターエンドポイントを使用します。名前と UUID による検索では、まず印刷版を特定し、次に選択した言語でその印刷版をリクエストします。翻訳が利用できない場合は、検索エラーが返されます。
• get_card_prices は、24 時間のカード詳細キャッシュとは独立した、専用の 6 時間キャッシュを使用します。
• デッキリストの分析では、まずカード名を完全一致で解決し、一致しない場合はファジー検索にフォールバックします。ファジー検索で解決された項目はレスポンスに報告されます。入力は 64 KiB、ユニーク名 100 件、合計カード数 10,000 枚、1 エントリーあたり 1,000 枚に制限されています。
• MCP ツール、プロンプト、またはリソース読み取りをキャンセルすると、キューに入っている Scryfall の処理は停止します。別のアクティブな呼び出し元と共有されている検索やリソース読み取りは、その呼び出し元が完了またはキャンセルするまで続行されます。バルクリソースをキャンセルするとストリームが停止し、不完全なスナップショットはクリーンアップされます。シャットダウン時は、実行中のバルク再構築のクリーンアップが完了するまで待機します。
• stdio サーバーは、クライアントが入力を閉じるとシャットダウンします。不正な HTTP URL または Host ヘッダーには、サーバーを終了せず HTTP 400 を返します。
• プロンプトの検証エラーでは、対処に役立つメッセージが維持され、MCP の無効なパラメーター用エラーコードが使用されます。上流のプロンプトエラーには、安全なステータス情報または再試行情報が含まれます。
• suggest_mana_base は、ヒューリスティックに基づく土地の枚数とサイクルのカテゴリを返します。各カードの使用可否や色の適合性は、別途確認が必要です。割り当てられたスロットはすべて含まれ、該当するサイクルがない場合は汎用のマナ調整カテゴリが使用されます。特殊な土地要件には現在対応しておらず、空でない special_requirements 入力には検証エラーが返されます。
• デッキ規模のツールでは、Scryfall がカード検索をスロットリングした場合、分析結果の一部、または明示的な再試行待ち時間のメッセージが返されることがあります。
• ストリーミング可能な HTTP セッションは HTTP_SESSION_IDLE_MS が経過すると期限切れになり、HTTP_SESSION_CLEANUP_INTERVAL_MS ごとに確認されます。
• 期限切れまたは不明な HTTP セッション ID を含むリクエストには 404 が返されます。クライアントは古い ID を使わずに新しいセッションを初期化して復旧します。必須のセッション ID がないリクエストには 400 が返されます。
• ループバック以外への HTTP バインドには、ベアラートークン認証と HTTP_TRUST_PROXY_TLS=true が必要です。これは、信頼できる HTTPS プロキシまたはトンネルが、平文のリスナーを保護していることを示します。Origin の許可リストは追加のブラウザーポリシーであり、認証の仕組みではありません。
• GET /health はレディネスチェックです。Scryfall のサーキットブレーカーが開いている場合を含め、必須サービスが劣化しているときは HTTP 503 を返します。

ローカル HTTP の起動例：

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

ツール呼び出しの例

build_scryfall_query

{
  "natural_query": "blue counterspells under $20 for modern",
  "optimize_for": "precision"
}

search_cards

{
  "query": "c:r t:instant mv=1",
  "limit": 10,
  "order": "name"
}

search_sets

{
  "type": "expansion",
  "released_after": "2020-01-01"
}

find_synergistic_cards

{
  "focus_card": "Obeka, Splitter of Seconds",
  "synergy_type": "theme",
  "format": "commander",
  "color_identity": "UBR",
  "limit": 12
}

統率者戦のようなワークフローでは、解決可能なカードではなくテーマに焦点を当てる場合、color_identityを渡してください。焦点がカードに解決される場合、ツールはそのカードの固有色を推測し、指定されたフォーマットの適正、Arenaでの利用可否、固有色で最終結果を絞り込みます。

analyze_deck_composition

{
  "deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
  "format": "modern",
  "strategy": "aggro"
}

Claude Desktopとの連携

ビルドしたstdioエントリーポイントをClaude Desktopの設定に追加してください。

macOSのパス：~/Library/Application Support/Claude/claude_desktop_config.json

Windowsのパス：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/scryfall-mcp/dist/index.js"]
    }
  }
}

運用上の注意

• レート制限はプロセス内で適用されます。Scryfall APIへの一般的なリクエストではデフォルトの最小間隔が100 ms、Scryfallの2/secカードエンドポイントでは最小間隔が500 msです。
• 検索結果、カードの詳細、価格、セット、バルクスナップショットは、上限付きのインメモリキャッシュに保存されます。
• バルクカードリソースはディスク経由で再構築され、シリアライズ済みのスナップショットを事前に保存することで、繰り返しの読み取りにかかるコストを抑えます。キャッシュの保持量には上限がありますが、バルクリソースの応答を生成する際には、シリアライズ済みの応答テキスト全体をプロセスのメモリ上に保持する必要があります。
• セットのフィルタリングでは、誤ったフィルター済みキャッシュの再利用を防ぐため、正規の/setsデータセットを1つ使用します。
• ヘルスチェックはScryfallMCPServer.healthCheck()とHTTPの/healthエンドポイントから利用できます。
• MCPコネクターでJSON-RPC/SSEのデシリアライズエラーが報告された場合は、未加工のHTTPスモークパスと比較してください。

npm run dev:http:local
npm run smoke:http

スモークコマンドが成功した場合は、コネクターのエラーテキストとスモーク出力を一緒に記録してください。これにより、ローカルエンドポイントのフレーミングとコネクター固有の解析を切り分けられます。

ドキュメント一覧

現在の正式なドキュメント：

• PURPOSE.md
• CONTRIBUTING.md
• SECURITY.md
• SCRYFALL_COMPLIANCE.md

ライセンス

MIT