Scryfall MCP Server
Scryfall MCP-Server
Ein auf Scryfall basierender MCP-Server für Magic: The Gathering-Suche, Regelabfragen, Preisinformationen, Set-Erkennung und Deckbau-Workflows.
Das Projekt unterstützt derzeit:
stdioals primären Transport für lokale MCP-ClientsLocal-first Streamable HTTP via
src/http.ts14 MCP-Tools, 2 Ressourcen und 2 Prompts
Was er bereitstellt
Tools
search_cards: Führt Scryfall-Kartensuchen mit Paging, Sortierung und optionalem Preisfilter durch.get_card: Ruft eine einzelne Karte nach Name, Set/Sammlernummer oder Scryfall-ID ab.get_card_prices: Gibt Preisdaten mit optionalem Formatkontext und Alternativen zurück.random_card: Ruft eine zufällige Karte mit optionalen Filtern ab.search_sets: Sucht und filtert Magic-Sets.query_rules: Durchsucht die lokale Datei mit den umfassenden Regeln mit Kontext.build_scryfall_query: Wandelt natürliche Sprache in eine erklärbare Scryfall-Abfrage um.search_format_staples: Findet Staples und wichtige Karten für ein Format.search_alternatives: Findet günstigere, verbesserte oder ähnliche Karten.find_synergistic_cards: Findet Synergie-Karten für eine Karte, ein Thema oder einen Archetyp.batch_card_analysis: Analysiert mehrere Karten auf Legalität, Preise, Synergie oder Zusammensetzung.validate_brawl_commander: Überprüft die Legalität von Brawl- und Standard-Brawl-Commandern.analyze_deck_composition: Bewertet Decklisten auf Kurve, Farben und strukturelle Probleme.suggest_mana_base: Empfiehlt Länderanzahlen und Fixing-Pakete basierend auf Farbanforderungen.
Ressourcen
card-database://bulk: Zwischengespeicherter Oracle-Bulk-Snapshot.set-database://all: Zwischengespeicherter Set-Listen-Snapshot.
Prompts
analyze_cardbuild_deck
Related MCP server: MTG-MCP
Transporte
STDIO
Empfohlen für Claude Desktop, Codex, MCP Inspector und die meisten lokalen MCP-Clients.
npm run devnpm startStreamable HTTP
Verfügbar als separater Einstiegspunkt für lokale oder explizit kontrollierte Umgebungen.
npm run dev:httpnpm run start:httpFür lokale MCP-Tests:
npm run dev:http:local
npm run smoke:httpDer Smoke-Test prüft /health, führt eine MCP-initialize durch, sendet notifications/initialized und verifiziert tools/list.
Er führt außerdem repräsentative validate_brawl_commander- und search_cards-Tool-Aufrufe durch, sodass der lokale HTTP-Endpunkt über die reine Erkennung hinaus geprüft wird.
Aktuelles HTTP-Verhalten:
bindet standardmäßig an
127.0.0.1bedient
POST|GET|DELETEunter/mcpbedient
GET /healthlehnt standardmäßig
Origin-Header ab, die nicht vom Loopback stammen, sofernHTTP_ALLOWED_ORIGINSnicht gesetzt ist
Der HTTP-Einstiegspunkt ist heute nützlich, wird aber noch konservativ dokumentiert. Er wird hier nicht als Lösung für öffentliches Hosting präsentiert.
Einrichtung
Voraussetzungen
Node.js 18+
npm
Installation
git clone https://github.com/bmurdock/scryfall-mcp.git
cd scryfall-mcp
npm install
cp .env.example .envValidierung
npm run lint
npm run type-check
npm testBuild
npm run buildHäufige Befehle
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 inspectorKonfiguration
Siehe .env.example für die kanonischen Werte. Die wichtigsten Variablen im aktiven Gebrauch sind:
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
Betriebshinweise:
Scryfall-API-Aufrufe werden global durch den gemeinsamen Ratenbegrenzer serialisiert. Batch-Tools können mehrere lokale Abfragen planen, aber die Vervollständigung der vorgelagerten Scryfall-Anfragen bleibt konstruktionsbedingt nacheinander.
HTTP 429-Antworten werden nicht automatisch wiederholt. Der Server protokolliert das Drosselungsfenster von Scryfall und verzögert den Start der nächsten Anfrage, damit der Aufrufer entscheiden kann, ob er es erneut versuchen möchte.
CACHE_MAX_MEMORY_MBsteuert, ob große In-Memory-Snapshots, einschließlichcard-database://bulk, beibehalten werden können. Zu große Bulk-Snapshots können für den aktuellen Lesevorgang immer noch zurückgegeben werden, aber die Metadaten melden, dass sie nicht zwischengespeichert wurden.Die Decklisten-Analyse löst Kartennamen zuerst exakt auf, greift dann bei exakten Fehlern auf eine Fuzzy-Suche zurück und meldet alle Fuzzy-Auflösungen in der Antwort.
Deck-Skalierungs-Tools können eine Teilanalyse oder eine explizite "Retry-After"-Nachricht zurückgeben, wenn Scryfall die zugrunde liegenden Kartenabfragen drosselt.
Beispiel für einen lokalen HTTP-Start:
HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:httpBeispiel-Tool-Aufrufe
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
}Für Commander-ähnliche Workflows übergeben Sie color_identity, wenn der Fokus auf einem Thema liegt und nicht auf einer auflösbaren Karte. Wenn sich der Fokus auf eine Karte auflöst, leitet das Tool die Farbidentität dieser Karte ab und filtert die Endergebnisse nach der angeforderten Legalität, Arena-Verfügbarkeit und Farbidentität.
analyze_deck_composition
{
"deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
"format": "modern",
"strategy": "aggro"
}Claude Desktop-Integration
Fügen Sie den erstellten stdio-Einstiegspunkt zu Ihrer Claude Desktop-Konfiguration hinzu.
macOS-Pfad: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows-Pfad: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"scryfall": {
"command": "node",
"args": ["/absolute/path/to/scryfall-mcp/dist/index.js"]
}
}
}Betriebshinweise
Die Ratenbegrenzung wird prozessintern mit einem standardmäßigen Mindestintervall von 100 ms zwischen Scryfall-Anfragen durchgesetzt.
Suchantworten, Kartendetails, Preise, Sets und Bulk-Snapshots werden mit begrenzten In-Memory-Limits zwischengespeichert.
Die Bulk-Kartenressource speichert einen vorserialisierten Snapshot, um wiederholte Lesevorgänge kostengünstig zu halten.
Die Set-Filterung wird aus einem kanonischen, zwischengespeicherten
/sets-Datensatz abgeleitet, um eine falsche Wiederverwendung gefilterter Caches zu vermeiden.Gesundheitsprüfungen sind über
ScryfallMCPServer.healthCheck()und den HTTP-Endpunkt/healthverfügbar.Wenn ein MCP-Connector einen JSON-RPC/SSE-Deserialisierungsfehler meldet, vergleichen Sie diesen mit dem rohen HTTP-Smoke-Pfad:
npm run dev:http:local
npm run smoke:httpWenn der Smoke-Befehl erfolgreich ist, erfassen Sie den Connector-Fehlertext und die Smoke-Ausgabe zusammen; dies trennt das lokale Endpunkt-Framing vom Connector-spezifischen Parsing.
Dokumentationsübersicht
Aktuelle "Source-of-Truth"-Dokumente:
Lizenz
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