Scryfall MCP Server

Scryfall MCP Server

MCP server that exposes Scryfall (Magic: The Gathering) through simple, typed tools for MCP-compatible clients (Claude Desktop, Cursor, Continue, Zed, etc.). Now includes Commander Spellbook (combo database) integration.

Highlights

• High-level server API via McpServer with typed inputs/outputs
• Tools for common queries: full-text search, by colors/CMC/format, and Tagger-based searches
• SSE or stdio transports
• Polite rate limiting and 429 backoff (Scryfall and Commander Spellbook)
• Optional local cache of Tagger tag lists
• Optional local index mapping Scryfall oracle_id → Commander Spellbook card id

Requirements

• Node.js >= 18.17

Install & Build

• Install: npm install
• Build: npm run build

Run (stdio)

• node dist/index.js

Run (SSE HTTP)

• npm run start:sse
• Env: PORT=3000 (default), CORS_ORIGIN=* (optional)

Docker

• Build: docker build -t scryfall-mcp:latest .
• Run (SSE): docker run --rm -p 3000:3000 -v mcp_data:/data scryfall-mcp:latest
• Override env:
  • SCRYFALL_INTERVAL_MS=100 (rate limiter)
  • TAGGER_CACHE_PATH=/data/tagger-tags.json
  • SCRYFALL_BASE_URL=https://api.scryfall.com
  • CSB_INTERVAL_MS=100 (rate limiter for Commander Spellbook)
  • CSB_BASE_URL=https://backend.commanderspellbook.com
  • CSB_CARD_INDEX_PATH=/data/csb-card-index.json
  • CSB_CARD_INDEX_TTL_MS=86400000
• Stdio transport: docker run --rm -it scryfall-mcp:latest node dist/index.js

MCP Client Example (Claude Desktop)

Environment Variables

• SCRYFALL_BASE_URL: API base URL (default https://api.scryfall.com)
• SCRYFALL_INTERVAL_MS: Minimum ms between requests (default 100)
• SCRYFALL_MAX_RETRIES: Max retries on 429 (default 3)
• SCRYFALL_RETRY_BASE_MS: Base backoff ms (default 250)
• TAGGER_CACHE_PATH: Local JSON path for Tagger tag lists (default ./cache/tagger-tags.json, Docker default /data/tagger-tags.json)

Commander Spellbook (CSB):

• CSB_BASE_URL: API base URL (default https://backend.commanderspellbook.com)
• CSB_INTERVAL_MS: Minimum ms between requests (default 100)
• CSB_MAX_RETRIES: Max retries on 429 (default 3)
• CSB_RETRY_BASE_MS: Base backoff ms (default 250)
• CSB_CARD_INDEX_PATH: Cache file path for oracleId→CSB id index (default ./cache/csb-card-index.json)
• CSB_CARD_INDEX_TTL_MS: TTL for index reuse in ms (default 86400000 = 24h)

Tools (Scryfall)

• search_cards — Full-text search using Scryfall q syntax.
• get_card — Fetch a card by id or name (fuzzy optional).
• random_card — Random card, optional q filter.
• autocomplete — Autocomplete card names.
• list_sets — All sets.
• get_rulings — Rulings by card id.

Guided search tools (structured results):

• search_by_colors — Params: colors, mode (exact|contains|at_most), identity, include_colorless, page.
• search_by_cmc — Params: min, max, colors, type, page.
• search_by_format — Params: format, status (legal|banned|restricted), colors, page.

Tagger-powered tools:

• list_tagger_tags — Returns { function: string[], art: string[] } from docs page (cached).
• search_by_function_tag — Params: tags[], match (any|all), colors?, format?, page? (uses otag:).
• search_by_art_tag — Params: tags[], match (any|all), colors?, type?, page? (uses arttag:).
• read_tagger_cache — Read cached tags without network.
• refresh_tagger_tags — Force refresh tags and write cache.

Notes:

• Many tools return structuredContent with compact card summaries: name, mana_cost, type_line, oracle_text, set, collector_number, scryfall_uri, image, prices.
• Some basic tools return content text (JSON stringified) for compatibility.

Commander Spellbook Tools

• csb_parse_deck_text — Parse plain-text decklist to cards via CSB.
  • Input: { text: string }
• csb_find_combos_by_card_ids — Find combos included/almost-included by CSB numeric card IDs.
  • Input: { ids: number[], limit?: number, offset?: number }
• csb_variants_search — Search variants (combos) by filters like uses (card id) or produces (feature id).
  • Input: { uses?: number, produces?: number, of?: number, limit?: number, offset?: number }
• csb_card — Fetch CSB card by numeric id.
  • Input: { id: number }
• csb_build_card_index — Build and cache oracleId→CSB id index (paginates /cards).
• csb_read_card_index — Read the cached index without network.
• csb_lookup_by_oracle_ids — Map Scryfall oracle_id UUIDs to CSB numeric ids using the cached index.
  • Input: { oracleIds: string[] }
• csb_find_combos_by_names — Resolve names via Scryfall → oracle_id, map via cached index, then call find-my-combos.
  • Input: { names: string[], fuzzy?: boolean, limit?: number, offset?: number }

Notes:

• CSB’s card-list-from-text expects Content-Type: text/plain (handled by the tool).
• The csb_find_combos_by_names tool benefits from building the index first: run csb_build_card_index once per day or set a custom TTL.

API Etiquette

• All requests send a descriptive User-Agent.
• Default limiter targets ~10 req/s (100ms between starts) and backs off on HTTP 429, honoring Retry-After (applies to both Scryfall and CSB).

Development

• Build: npm run build
• StdIO dev: npm run start:stdio
• SSE dev: npm run start:sse
• random_card:
  • Input: { q?: string }
• autocomplete:
  • Input: { q: string }
• list_sets:
  • Input: none
• get_rulings:
  • Input: { id: uuid }

Notes

• Scryfall rate limits: be respectful (they suggest up to ~10 requests/sec). This server does not add extra rate limiting; your client should avoid flooding requests.
• Responses are returned as JSON content for maximum fidelity; clients can post-process or render summaries.

SSE Transport Endpoints

• Events stream (server -> client via EventSource): GET /sse
• Messages endpoint (client -> server): POST /messages

Point your MCP client’s SSE transport at these endpoints on your configured host/port.

Development

• Build: npm run build
• Start (built): npm start
• Edit source in src/ and rebuild.

License

No license specified. Add one if you plan to distribute.