Scryfall MCP Server

A Model Context Protocol (MCP) server that surfaces the Scryfall API for Magic: The Gathering card data. Deployed on Cloudflare Workers.

Quick Start

Configure your AI client to connect to the deployed instance of the server or download this repo and run it locally.

Claude Desktop

To use this MCP server with Claude Desktop, you'll need the mcp-remote proxy.

1. Open Claude Desktop settings: Settings > Developer > Edit Config

2. Add this configuration:

   {
     "mcpServers": {
       "scryfall": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://scryfall-mcp-server.colin-hauch.workers.dev/sse"
         ]
       }
     }
   }
   

3. Restart Claude Desktop

Local Development

{
  "mcpServers": {
    "scryfall": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8787/sse"]
    }
  }
}

Cloudflare AI Playground

1. Go to https://playground.ai.cloudflare.com/
2. Pick a model (mistral-small-3.1-24b-instruct is selected by default here)
3. Enter your MCP server URL: https://scryfall-mcp-server.colin-hauch.workers.dev
4. Start using the Scryfall tools!

Other MCP Clients

Any MCP-compatible client can connect to the server via:

• SSE endpoint: /sse (recommended for most clients)
• MCP endpoint: /mcp (for clients that support direct MCP protocol)

Features

• Search Cards: Find Magic cards using Scryfall's powerful search syntax
• Get Card Details: Retrieve specific cards by name with fuzzy matching
• Random Cards: Get random cards with optional filtering
• Field Selection: Control exactly which card data is returned to optimize context usage

Available MCP Tools

search_cards

Search for Magic cards using Scryfall's search syntax. Returns all results from the current page (up to 175 cards).

Parameters:

• query (string, required): Search query using Scryfall syntax
  • Examples: "lightning bolt", "type:creature color:red", "f:commander pow>=5"
• unique (string, optional): Strategy for omitting similar cards
  • Options: "cards", "art", "prints"
• order (string, optional): Sort order
  • Options: "name", "set", "released", "rarity", "color", "usd", "cmc", "power", "toughness", "edhrec"
• dir (string, optional): Sort direction
  • Options: "auto", "asc", "desc"
• page (number, optional): Page number for pagination (1-based). Use to access results beyond the first 175.
• fields (array or string, optional): Control which card data is returned (defaults to "minimal")
  • Predefined groups: "minimal", "gameplay", "pricing", "imagery", "full"
  • Custom array: ["name", "mana_cost", "prices.usd"]
  • See "Field Selection" section below for details

Example:

{
  "query": "type:creature power>=5",
  "order": "power",
  "fields": "gameplay"
}

Pagination example:

{
  "query": "type:creature",
  "page": 2
}

get_card_details

Get detailed information for one or more cards by exact name. Uses Scryfall's collection endpoint for efficient bulk lookups (up to 75 cards per request with a single API call).

Parameters:

• names (array of strings, required): Exact card names to search for (can be single or multiple, max 75)
• set (string, optional): Filter by set code for all cards (e.g., "mkm", "one")
• fields (array or string, optional): Control which card data is returned (defaults to "gameplay")
  • Predefined groups: "minimal", "gameplay", "pricing", "imagery", "full"
  • Custom array: ["name", "mana_cost", "prices.usd"]
  • See "Field Selection" section below for details

Note: This tool uses exact name matching. Card names must match exactly (case-insensitive).

Examples:

Single card:

{
  "names": ["Black Lotus"],
  "fields": ["name", "mana_cost", "prices", "legalities"]
}

Multiple cards:

{
  "names": ["Black Lotus", "Mox Ruby", "Ancestral Recall"],
  "fields": "gameplay"
}

get_random_card

Get a random Magic card.

Parameters:

• query (string, optional): Filter random selection using Scryfall search syntax (e.g., "type:creature")
• fields (array or string, optional): Control which card data is returned
  • Predefined groups: "minimal", "gameplay", "pricing", "imagery", "full"
  • Custom array: ["name", "mana_cost", "prices.usd"]
  • See "Field Selection" section below for details

Example:

{
  "query": "type:legendary",
  "fields": "minimal"
}

Field Selection

All card-related tools support optional field selection to control which data is returned, helping you optimize context usage in your AI workflows.

Predefined Field Groups

Use these convenient presets for common use cases:

• "minimal" - Essential card info: name, mana_cost, type_line, oracle_text
• "gameplay" - Gameplay-relevant data: minimal + colors, color_identity, cmc, power, toughness, loyalty, rarity
• "pricing" - Price information: name, prices
• "imagery" - Image data: name, artist, image_uris, illustration_id
• "full" - All available fields (default when fields is not specified)

Custom Field Arrays

Specify exactly which fields you need:

{
  "name": "Lightning Bolt",
  "fields": ["name", "mana_cost", "oracle_text", "prices.usd"]
}

Nested Fields

Access nested object properties using dot notation:

{
  "query": "format:vintage",
  "fields": ["name", "prices.usd", "prices.eur", "image_uris.normal"]
}

Available Fields Reference

The MCP server provides a resource at scryfall://fields/reference with a complete list of all available fields. Access this through your MCP client to see all options.

Examples

Minimal context for quick lookups:

{
  "query": "lightning bolt",
  "fields": "minimal"
}

Price checking:

{
  "names": ["Mox Ruby"],
  "fields": ["name", "set", "prices.usd", "prices.usd_foil"]
}

Gameplay analysis:

{
  "query": "type:creature cmc<=2",
  "fields": "gameplay"
}

MCP Resources

The server exposes additional resources for enhanced functionality:

scryfall://search-syntax/full

Complete reference guide for Scryfall search syntax with all keywords, operators, and advanced filters.

scryfall://fields/reference

Complete list of available fields for custom field selection with examples and usage guidance.

Rate Limiting & Performance

The server implements comprehensive rate limiting to respect Scryfall API guidelines:

• Proactive rate limiting: 100ms delay between requests
• Automatic retries: Exponential backoff on HTTP 429 errors (1s → 2s → 4s)
• Error handling: Structured error responses with detailed messages

License

This project is provided as-is for portfolio and educational purposes.