Scryfall MCP Server
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:
stdiocomo transporte principal para clientes MCP localesHTTP transmitible (Streamable) local primero a través de
src/http.ts14 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_cardbuild_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 devnpm startHTTP Transmitible
Disponible como punto de entrada independiente para entornos locales o controlados explícitamente.
npm run dev:httpnpm run start:httpPara pruebas MCP locales:
npm run dev:http:local
npm run smoke:httpLa 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.1por defectosirve
POST|GET|DELETEen/mcpsirve
GET /healthrechaza encabezados
Originque no sean de bucle local (loopback) por defecto, a menos que se establezcaHTTP_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 .envValidación
npm run lint
npm run type-check
npm testConstrucción
npm run buildComandos 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 inspectorConfiguración
Consulta .env.example para ver los valores canónicos. Las variables principales en uso activo son:
SCRYFALL_USER_AGENTRATE_LIMIT_MSRATE_LIMIT_QUEUE_MAXSCRYFALL_TIMEOUT_MSCACHE_MAX_SIZECACHE_MAX_MEMORY_MBLOG_LEVELNODE_ENVHEALTHCHECK_DEEPHTTP_HOSTHTTP_PORTHTTP_MCP_PATHHTTP_HEALTH_PATHHTTP_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_MBcontrola si se pueden retener instantáneas grandes en memoria, incluidacard-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:httpEjemplo 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
/setsen 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:httpSi 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 toolsanalyze_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for I Want My MTG that enables conversational search of Magic: The Gathering cards/sets and inventory management via API tools.61418 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA 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.1MIT
- AlicenseAqualityDmaintenanceMCP 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.4MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that searches and retrieves Magic: The Gathering card data from the Scryfall API.74,083 npmMIT