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)

{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "SCRYFALL_INTERVAL_MS": "100",
        "TAGGER_CACHE_PATH": "C:/path/to/cache/tagger-tags.json"
      }
    }
  }
}

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.

Scryfall MCP Server

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)

{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "SCRYFALL_INTERVAL_MS": "100",
        "TAGGER_CACHE_PATH": "C:/path/to/cache/tagger-tags.json"
      }
    }
  }
}

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.