mtg-mcp

Un servidor minimalista del Protocolo de Contexto de Modelo (MCP) en Python que expone búsquedas de cartas de Magic: The Gathering (y una comprobación de estado) a cualquier cliente LLM compatible con MCP.

Complemento de la entrada del blog: Tutorial del Protocolo de Contexto de Modelo: Construye tu primer servidor

La publicación recorre este repositorio de principio a fin: qué es MCP, cómo funcionan las dos herramientas, la progresión de Scryfall de falso el día 1 a real el día 2, y cómo conectarlo a Claude Desktop.

Qué hace

Dos herramientas, expuestas por un proceso de Python a través de stdio de MCP:

• health.check — devuelve la versión del servidor, la hora UTC actual y un contador simple de "racha de aprendizaje" persistido en streak.json. La herramienta más simple posible. Sin dependencias externas.

• mtg.card_lookup — toma el nombre de una carta y devuelve la línea de tipo de la carta, el texto de oráculo, el valor de maná y la URL de la imagen. Llama al endpoint de nombres difusos de Scryfall.

El contrato de mtg.card_lookup se diseñó primero; la implementación pasó por una progresión deliberada de falso a real. Consulta docs/01-spec-scryfall-integration.md para ver la especificación completa.

Related MCP server: Scryfall MCP Server

Inicio rápido

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

El servidor se ejecuta a través de stdio por defecto y se bloqueará esperando a que un cliente MCP se conecte. Eso es correcto: apunta tu cliente al comando python src/server.py (con rutas absolutas) para empezar a llamar a las herramientas.

Se recomienda Python 3.11 o superior. uvloop es opcional y se omite automáticamente en Windows.

Conectándolo a Claude Desktop

Añade una entrada a tu claude_desktop_config.json:

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

Usa rutas absolutas tanto para el intérprete como para el script; Claude Desktop inicia el servidor por sí mismo, por lo que una ~ o una ruta relativa no se resolverán. Cierra Claude Desktop completamente y vuelve a abrirlo después de guardar.

Estructura del repositorio

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

El directorio logs/ y streak.json se crean en tiempo de ejecución.

Día 1 → Día 2: cómo evolucionó este repositorio

La primera versión de mtg.card_lookup devolvía una respuesta falsa codificada (que solo coincidía con el nombre Atraxa). El objetivo de empezar con algo falso era probar la conexión: que el cliente MCP pudiera encontrar la herramienta, llamarla y analizar la forma de la respuesta, antes de depurar cualquier capa HTTP.

Una vez confirmada la conexión, se cambió la misma función para llamar a Scryfall. La firma de la función, el esquema de entrada y la forma de retorno no cambiaron. El contrato se mantuvo. Esa progresión es el punto central de la entrada del blog complementaria; la especificación para el cambio se encuentra en docs/01-spec-scryfall-integration.md, el plan en docs/02-plan-scryfall-integration.md y la retrospectiva en docs/03-lessons-learned.md.

Dependencias

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

Las versiones no están fijadas en este repositorio. Si necesitas reproducibilidad, fíjalas en tu instalación.

Licencia

MIT — Copyright (c) 2026 Jason Belk.

Lecturas adicionales

• La publicación complementaria: Tutorial del Protocolo de Contexto de Modelo: Construye tu primer servidor

• Documentación oficial de MCP: modelcontextprotocol.io

• Anuncio de lanzamiento de MCP de Anthropic: anthropic.com/news/model-context-protocol

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