Skip to main content
Glama
Scryfall MCP Server

Scryfall MCP Server

by bmurdock

Servidor MCP de Scryfall

Servidor MCP respaldado por Scryfall para búsquedas de Magic: The Gathering, consulta de reglas, precios, descubrimiento de colecciones y flujos de trabajo de construcción de mazos.

El proyecto actualmente admite:

  • stdio como transporte principal para clientes MCP locales

  • HTTP transmitible (Streamable) local primero a través de src/http.ts

  • 14 herramientas MCP, 2 recursos y 2 prompts

Qué expone

Herramientas

  • search_cards: Ejecuta búsquedas de cartas en Scryfall con paginación, ordenamiento y filtrado de precios opcional.

  • get_card: Obtiene una carta por nombre, colección/número de coleccionista o ID de Scryfall.

  • get_card_prices: Devuelve datos de precios con contexto de formato y alternativas opcionales.

  • random_card: Obtiene una carta aleatoria con filtros opcionales.

  • search_sets: Busca y filtra colecciones de Magic.

  • query_rules: Busca en el archivo de reglas completas local con contexto.

  • build_scryfall_query: Convierte lenguaje natural en una consulta de Scryfall explicable.

  • search_format_staples: Encuentra cartas básicas y fundamentales para un formato.

  • search_alternatives: Encuentra cartas más baratas, mejoradas o similares.

  • find_synergistic_cards: Encuentra piezas de sinergia para una carta, tema o arquetipo.

  • batch_card_analysis: Analiza múltiples cartas en cuanto a legalidad, precios, sinergia o composición.

  • validate_brawl_commander: Comprueba la legalidad de comandantes en Brawl y Brawl Estándar.

  • analyze_deck_composition: Evalúa listas de mazos en cuanto a curva, colores y problemas estructurales.

  • suggest_mana_base: Recomienda recuentos de tierras y paquetes de fijación de maná a partir de los requisitos de color.

Recursos

  • card-database://bulk: Instantánea masiva de Oracle en caché.

  • set-database://all: Instantánea de la lista de colecciones en caché.

Prompts

  • analyze_card

  • build_deck

Related MCP server: MTG-MCP

Transportes

STDIO

Recomendado para Claude Desktop, Codex, MCP Inspector y la mayoría de los clientes MCP locales.

npm run dev
npm start

HTTP Transmitible

Disponible como punto de entrada independiente para entornos locales o controlados explícitamente.

npm run dev:http
npm run start:http

Para pruebas MCP locales:

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

La prueba de humo verifica /health, realiza la initialize de MCP, envía notifications/initialized y verifica tools/list. También realiza llamadas representativas a las herramientas validate_brawl_commander y search_cards para que el punto final HTTP local se verifique más allá del descubrimiento.

Comportamiento actual de HTTP:

  • se vincula a 127.0.0.1 por defecto

  • sirve POST|GET|DELETE en /mcp

  • sirve GET /health

  • rechaza encabezados Origin que no sean de bucle local (loopback) por defecto, a menos que se establezca HTTP_ALLOWED_ORIGINS

El punto de entrada HTTP es útil hoy en día, pero todavía está documentado de forma conservadora. No se presenta aquí como una solución de alojamiento público.

Configuración

Requisitos previos

  • Node.js 18+

  • npm

Instalación

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

Validación

npm run lint
npm run type-check
npm test

Construcción

npm run build

Comandos comunes

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

Configuración

Consulta .env.example para ver los valores canónicos. Las variables principales en uso activo son:

  • 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

Notas operativas:

  • Las llamadas a la API de Scryfall se serializan globalmente mediante el limitador de tasa compartido. Las herramientas por lotes pueden programar múltiples búsquedas locales, pero la finalización de la solicitud a Scryfall ascendente sigue siendo una a la vez por diseño.

  • Las respuestas HTTP 429 no se reintentan automáticamente. El servidor registra la ventana de limitación de Scryfall y retrasa el inicio de la siguiente solicitud para que los llamadores puedan decidir si reintentar.

  • CACHE_MAX_MEMORY_MB controla si se pueden retener instantáneas grandes en memoria, incluida card-database://bulk. Las instantáneas masivas de gran tamaño aún pueden devolverse para la lectura actual, pero los metadatos informarán que no se almacenaron en caché.

  • El análisis de listas de mazos resuelve los nombres de las cartas exactamente primero, luego recurre a la búsqueda difusa para los errores exactos e informa cualquier resolución difusa en la respuesta.

  • Las herramientas a escala de mazo pueden devolver un análisis parcial o un mensaje explícito de reintento después de que Scryfall limite las búsquedas de cartas subyacentes.

Ejemplo de inicio de HTTP local:

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

Ejemplo de llamadas a herramientas

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
}

Para flujos de trabajo tipo Commander, pasa color_identity cuando el enfoque sea un tema en lugar de una carta resoluble. Cuando el enfoque se resuelve en una carta, la herramienta infiere la identidad de color de esa carta y filtra los resultados finales por la legalidad solicitada, la disponibilidad en Arena y la identidad de color.

analyze_deck_composition

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

Integración con Claude Desktop

Añade el punto de entrada stdio compilado a tu configuración de Claude Desktop.

Ruta en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Ruta en Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Notas operativas

  • La limitación de tasa se aplica en el proceso con un intervalo mínimo predeterminado de 100 ms entre solicitudes a Scryfall.

  • Las respuestas de búsqueda, los detalles de las cartas, los precios, las colecciones y las instantáneas masivas se almacenan en caché con límites de memoria acotados.

  • El recurso de cartas masivas almacena una instantánea pre-serializada para que las lecturas repetidas sean económicas.

  • El filtrado de colecciones se deriva de un conjunto de datos /sets en caché canónico para evitar el uso incorrecto de caché filtrada.

  • Las comprobaciones de estado están disponibles a través de ScryfallMCPServer.healthCheck() y el punto final HTTP /health.

  • Si un conector MCP informa un error de deserialización JSON-RPC/SSE, compáralo con la ruta de humo HTTP sin procesar:

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

Si el comando de humo tiene éxito, captura el texto de error del conector y la salida de humo juntos; eso separa el marco del punto final local del análisis específico del conector.

Mapa de documentación

Documentos fuente de verdad actuales:

Licencia

MIT

Available Tools

14 tools
analyze_deck_compositionC

Analyze deck composition, mana curve, card types, and provide balance recommendations

Inputs: deck_list (required), commander, format, strategy.

batch_card_analysisC

Analyze multiple cards for legality, prices, synergies, or deck composition

Inputs: analysis_type (required), card_list (required), currency, format, +2 more.

build_scryfall_queryB

Convert natural language requests into optimized Scryfall search queries with explanations and alternatives

Inputs: natural_query (required), explain_mapping, format, include_alternatives, +4 more.

find_synergistic_cardsC

Find cards that synergize with a specific card, theme, or archetype

Inputs: focus_card (required), arena_only, exclude_colors, format, +4 more.

get_cardB

Get detailed information about a specific Magic: The Gathering card by name, set code+number, or Scryfall ID

Inputs: identifier (required), face, include_image, lang, +1 more.

get_card_pricesB

Get current price information for a Magic: The Gathering card by name, set/number, or Scryfall ID

Inputs: card_identifier (required), currency, format_context, include_alternatives, +1 more.

query_rulesC

Search Magic: The Gathering comprehensive rules for specific interactions and rule clarifications

Inputs: query (required), context_lines, exact_match, section.

random_cardB

Get a random Magic: The Gathering card, optionally filtered by format or search criteria

Inputs: archetype, exclude_reprints, format, price_range, +3 more.

search_alternativesB

Find budget alternatives, upgrades, or functionally similar cards

Inputs: direction (required), target_card (required), format, limit, +3 more.

search_cardsA

Search for Magic: The Gathering cards using Scryfall search syntax. Supports complex queries with operators like color:, type:, set:, etc.

Inputs: query (required), arena_only, direction, format, +8 more.

search_format_staplesC

Find format staples, meta cards, and role-specific cards for competitive play

Inputs: format (required), color_identity, limit, max_price, +2 more.

search_setsC

Search for Magic: The Gathering sets with optional filtering by name, type, and release dates

Inputs: query, released_after, released_before, type.

suggest_mana_baseC

Suggest optimal mana base composition and land recommendations for a deck

Inputs: color_requirements (required), average_cmc, budget, color_intensity, +4 more.

validate_brawl_commanderB

Validate if a card can be a legal commander in Brawl or Standard Brawl formats

Inputs: card_identifier (required), format (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no significant overlap. For example, get_card retrieves a single card, search_cards handles complex queries, and analyze_deck_composition focuses on deck analysis, making misselection unlikely.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, such as get_card, search_cards, and analyze_deck_composition. This predictability aids in agent understanding and usage.

    Tool Count5/5

    With 14 tools, the server is well-scoped for Magic: The Gathering card and deck management. Each tool serves a specific function, from card retrieval to deck analysis, without feeling excessive or insufficient.

    Completeness5/5

    The tool surface comprehensively covers the domain, including card search, price checks, deck analysis, rules queries, and format validation. There are no obvious gaps, supporting full agent workflows for MTG-related tasks.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for I Want My MTG that enables conversational search of Magic: The Gathering cards/sets and inventory management via API tools.
      61
      418 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive Model Context Protocol server that provides AI assistants with rich Magic: The Gathering information, including card data, comprehensive rules, EDHREC recommendations, combo interactions, and intelligent Commander deck generation.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for searching and retrieving Magic: The Gathering card information via the Scryfall API, with support for field presets, multiple output formats, and automatic rate limiting.
      4
      MIT