Skip to main content
Glama
Scryfall MCP Server

Scryfall MCP Server

by bmurdock

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:

  • stdio als primären Transport für lokale MCP-Clients

  • Local-first Streamable HTTP via src/http.ts

  • 14 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_card

  • build_deck

Related MCP server: MTG-MCP

Transporte

STDIO

Empfohlen für Claude Desktop, Codex, MCP Inspector und die meisten lokalen MCP-Clients.

npm run dev
npm start

Streamable HTTP

Verfügbar als separater Einstiegspunkt für lokale oder explizit kontrollierte Umgebungen.

npm run dev:http
npm run start:http

Für lokale MCP-Tests:

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

Der 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.1

  • bedient POST|GET|DELETE unter /mcp

  • bedient GET /health

  • lehnt standardmäßig Origin-Header ab, die nicht vom Loopback stammen, sofern HTTP_ALLOWED_ORIGINS nicht 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 .env

Validierung

npm run lint
npm run type-check
npm test

Build

npm run build

Hä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 inspector

Konfiguration

Siehe .env.example für die kanonischen Werte. Die wichtigsten Variablen im aktiven Gebrauch sind:

  • 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

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_MB steuert, ob große In-Memory-Snapshots, einschließlich card-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:http

Beispiel-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 /health verfü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:http

Wenn 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 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