mtg-mcp

Magic: The Gatheringのカード検索（およびヘルスチェック）をMCP互換のLLMクライアントに公開する、Python製の最小限のModel Context Protocolサーバーです。

ブログ記事の補足: Model Context Protocol Tutorial: Build Your First Server

この記事では、このリポジトリを最初から最後まで解説しています。MCPとは何か、2つのツールがどのように機能するか、Day-1（ダミー）からDay-2（実運用）へのScryfall統合の進め方、そしてClaude Desktopへの接続方法について説明しています。

機能

MCP stdio経由で1つのPythonプロセスによって公開される2つのツール：

• health.check — サーバーのバージョン、現在のUTC時刻、および streak.json に保存された単純な「学習ストリーク」カウンターを返します。最もシンプルなツールであり、外部依存関係はありません。

• mtg.card_lookup — カード名を受け取り、そのカードのタイプ行、オラクルテキスト、マナコスト、画像URLを返します。Scryfallの曖昧検索エンドポイントを呼び出します。

mtg.card_lookup のコントラクトは最初に設計され、実装はダミーから実運用へと慎重に進められました。仕様に基づいた詳細な記述については docs/01-spec-scryfall-integration.md を参照してください。

Related MCP server: Scryfall MCP Server

クイックスタート

git clone https://github.com/jabelk/mtg-mcp.git
cd mtg-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
python src/server.py

サーバーはデフォルトでstdio経由で実行され、MCPクライアントの接続を待機してブロックします。これは正常な動作です。クライアントで python src/server.py コマンド（絶対パスを使用）を指定してツールを呼び出してください。

Python 3.11以降を推奨します。uvloop はオプションであり、Windowsでは自動的にスキップされます。

Claude Desktopへの接続

claude_desktop_config.json にエントリを追加します：

{
  "mcpServers": {
    "mtg": {
      "command": "/absolute/path/to/mtg-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/mtg-mcp/src/server.py"]
    }
  }
}

インタープリタとスクリプトの両方に絶対パスを使用してください。Claude Desktopはサーバー自体を起動するため、~ や相対パスでは解決されません。保存後、Claude Desktopを完全に終了してから再起動してください。

リポジトリの構成

mtg-mcp/
├── src/
│   ├── server.py            # MCP server entry point — registers the two tools
│   └── tools/
│       ├── __init__.py
│       └── card_lookup.py   # Scryfall integration (Day-2 real implementation)
├── docs/
│   ├── 01-spec-scryfall-integration.md   # spec for the Day-1 → Day-2 swap
│   ├── 02-plan-scryfall-integration.md   # implementation plan
│   └── 03-lessons-learned.md             # retrospective
├── requirements.txt
├── LICENSE
└── README.md

logs/ ディレクトリと streak.json は実行時に作成されます。

Day 1 → Day 2: このリポジトリの進化

mtg.card_lookup の最初のバージョンは、ハードコードされたダミーのレスポンス（Atraxa という名前のみに一致）を返していました。ダミーから始めた理由は、MCPクライアントがツールを見つけ、呼び出し、レスポンスの形式を解析できるという配線を、HTTP層のデバッグの前に証明するためでした。

配線が確認された後、同じ関数をScryfallを呼び出すように切り替えました。関数のシグネチャ、入力スキーマ、戻り値の形式は変更されていません。コントラクトは維持されました。この進め方こそが、補足ブログ記事の核心です。切り替えの仕様は docs/01-spec-scryfall-integration.md に、計画は docs/02-plan-scryfall-integration.md に、振り返りは docs/03-lessons-learned.md に記載されています。

依存関係

mcp        # the official MCP Python SDK
uvloop     # faster event loop (skipped on Windows)
httpx      # HTTP client for the Scryfall call

このリポジトリではバージョンは固定されていません。再現性が必要な場合は、インストール時にバージョンを固定してください。

ライセンス

MIT — Copyright (c) 2026 Jason Belk.

参考文献

• 補足記事: Model Context Protocol Tutorial: Build Your First Server

• 公式MCPドキュメント: modelcontextprotocol.io

• AnthropicのMCP発表アナウンス: anthropic.com/news/model-context-protocol

• Scryfall API: scryfall.com/docs/api