Scryfall MCPサーバー

Magic: The Gatheringの検索、ルール参照、価格確認、セット探索、デッキ構築ワークフローのためのScryfall対応MCPサーバーです。

現在、以下の機能をサポートしています：

• ローカルMCPクライアント向けの主要トランスポートとしての stdio

• src/http.ts によるローカル優先のストリーミング可能なHTTP

• 14個のMCPツール、2個のリソース、2個のプロンプト

提供機能

ツール

• search_cards: ページング、ソート、オプションの価格フィルタリングを使用してScryfallカード検索を実行します。

• get_card: 名前、セット/コレクター番号、またはScryfall IDでカードを1枚取得します。

• get_card_prices: オプションのフォーマットコンテキストと代替案を含む価格データを返します。

• random_card: オプションのフィルターを使用してランダムなカードを取得します。

• search_sets: マジックのセットを検索およびフィルタリングします。

• query_rules: コンテキスト付きでローカルの包括的ルールファイルを検索します。

• build_scryfall_query: 自然言語を説明可能なScryfallクエリに変換します。

• search_format_staples: フォーマットの定番カードや役割を果たすカードを見つけます。

• search_alternatives: より安価なカード、アップグレード版、または類似のカードを見つけます。

• find_synergistic_cards: カード、テーマ、またはアーキタイプに適したシナジーカードを見つけます。

• batch_card_analysis: 複数のカードの適法性、価格、シナジー、または構成を分析します。

• validate_brawl_commander: ブロールおよびスタンダード・ブロールの統率者の適法性を確認します。

• analyze_deck_composition: デッキリストのマナカーブ、色、構造上の問題を評価します。

• suggest_mana_base: 色の要件から土地の枚数とマナ基盤のパッケージを推奨します。

リソース

• card-database://bulk: キャッシュされたOracleバルクスナップショット。

• set-database://all: キャッシュされたセットリストスナップショット。

プロンプト

• analyze_card

• build_deck

Related MCP server: MTG-MCP

トランスポート

STDIO

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

npm run dev

npm start

ストリーミング可能な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の動作:

• デフォルトで 127.0.0.1 にバインド

• /mcp で POST|GET|DELETE を提供

• GET /health を提供

• HTTP_ALLOWED_ORIGINS が設定されていない限り、デフォルトでループバック以外の Origin ヘッダーを拒否

HTTPエントリーポイントは現在有用ですが、保守的にドキュメント化されています。ここではパブリックホスティングの手段としては提示していません。

セットアップ

前提条件

• Node.js 18+

• npm

インストール

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

検証

npm run lint
npm run type-check
npm test

ビルド

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 lint
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_ALLOWED_ORIGINS

運用上の注意:

• Scryfall API呼び出しは、共有レートリミッターによってグローバルにシリアル化されます。バッチツールは複数のローカル検索をスケジュールする場合がありますが、上流のScryfallリクエストの完了は設計上1つずつ行われます。

• HTTP 429レスポンスは自動的に再試行されません。サーバーはScryfallのスロットルウィンドウを記録し、次のリクエスト開始を遅延させるため、呼び出し側が再試行するかどうかを判断できます。

• CACHE_MAX_MEMORY_MB は、card-database://bulk を含む大規模なメモリ内スナップショットを保持できるかどうかを制御します。サイズ超過のバルクスナップショットは現在の読み取りに対して返される可能性がありますが、メタデータではキャッシュされなかったことが報告されます。

• デッキリスト分析は、まずカード名を正確に解決し、一致しない場合はあいまい検索にフォールバックし、あいまい解決の結果をレスポンスで報告します。

• デッキ規模のツールは、Scryfallが基盤となるカード検索をスロットルした場合、部分的な分析結果や明示的な再試行メッセージを返すことがあります。

ローカル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リクエスト間のデフォルトの最小間隔は100msです。

• 検索レスポンス、カード詳細、価格、セット、およびバルクスナップショットは、メモリ制限内でキャッシュされます。

• バルクカードリソースは、繰り返し読み取りを高速化するために事前にシリアル化されたスナップショットを保存します。

• セットのフィルタリングは、誤ったフィルタ済みキャッシュの再利用を避けるため、1つの標準的なキャッシュ済み /sets データセットから派生しています。

• ヘルスチェックは 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