mtg-mcp

Ein minimaler Model Context Protocol-Server in Python, der Magic: The Gathering-Kartensuchen (sowie eine Gesundheitsprüfung) für jeden MCP-kompatiblen LLM-Client bereitstellt.

Begleitend zum Blogbeitrag: Model Context Protocol Tutorial: Build Your First Server

Der Beitrag führt durch dieses Repository von Anfang bis Ende: Was MCP ist, wie die beiden Tools funktionieren, die Entwicklung von Tag-1-Fake zu Tag-2-echt mit Scryfall und wie man es mit Claude Desktop verbindet.

Was es tut

Zwei Tools, die von einem Python-Prozess über MCP stdio bereitgestellt werden:

• health.check — gibt die Serverversion, die aktuelle UTC-Zeit und einen einfachen, in streak.json gespeicherten „Lern-Streak“-Zähler zurück. Das einfachstmögliche Tool. Keine externen Abhängigkeiten.

• mtg.card_lookup — nimmt einen Kartennamen entgegen und gibt die Kartenzeile, den Orakeltext, den Manawert und die Bild-URL zurück. Ruft den Scryfall-Endpunkt für unscharfe Namenssuche auf.

Der Vertrag für mtg.card_lookup wurde zuerst entworfen; die Implementierung durchlief eine bewusste Fake-zu-Echt-Entwicklung. Siehe docs/01-spec-scryfall-integration.md für die vollständige spezifikationsbasierte Dokumentation.

Related MCP server: Scryfall MCP Server

Schnellstart

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

Der Server läuft standardmäßig über stdio und blockiert, während er auf die Verbindung eines MCP-Clients wartet. Das ist korrekt – geben Sie Ihrem Client den Befehl python src/server.py (mit absoluten Pfaden), um mit dem Aufruf der Tools zu beginnen.

Python 3.11 oder neuer wird empfohlen. uvloop ist optional und wird unter Windows automatisch übersprungen.

Verbindung mit Claude Desktop

Fügen Sie einen Eintrag zu Ihrer claude_desktop_config.json hinzu:

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

Verwenden Sie absolute Pfade sowohl für den Interpreter als auch für das Skript; Claude Desktop startet den Server selbst, daher werden ~ oder relative Pfade nicht aufgelöst. Beenden Sie Claude Desktop vollständig und starten Sie es nach dem Speichern neu.

Repository-Struktur

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

Das Verzeichnis logs/ und die Datei streak.json werden zur Laufzeit erstellt.

Tag 1 → Tag 2: Wie sich dieses Repository entwickelt hat

Die erste Version von mtg.card_lookup gab eine fest codierte Fake-Antwort zurück (die nur auf den Namen Atraxa passte). Der Sinn des Starts mit einem Fake war es, die Verkabelung zu beweisen – dass der MCP-Client das Tool finden, aufrufen und die Antwortstruktur parsen konnte –, bevor die HTTP-Ebene debuggt wurde.

Sobald die Verkabelung bestätigt war, wurde dieselbe Funktion auf den Aufruf von Scryfall umgestellt. Die Funktionssignatur, das Eingabeschema und die Rückgabestruktur änderten sich nicht. Der Vertrag blieb bestehen. Diese Entwicklung ist der Kern des begleitenden Blogbeitrags; die Spezifikation für den Austausch befindet sich unter docs/01-spec-scryfall-integration.md, der Plan unter docs/02-plan-scryfall-integration.md und der Rückblick unter docs/03-lessons-learned.md.

Abhängigkeiten

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

Versionen sind in diesem Repository nicht fixiert. Wenn Sie Reproduzierbarkeit benötigen, fixieren Sie diese bei Ihrer Installation.

Lizenz

MIT — Copyright (c) 2026 Jason Belk.

Weiterführende Literatur

• Der begleitende Beitrag: Model Context Protocol Tutorial: Build Your First Server

• Offizielle MCP-Dokumentation: modelcontextprotocol.io

• Ankündigung des MCP-Starts durch Anthropic: anthropic.com/news/model-context-protocol

• Scryfall-API: scryfall.com/docs/api