scryfall-mcp

An MCP server that wraps the Scryfall API and gives any agent full access to Magic: The Gathering card data — search, rulings, sets, symbols, catalogs, and local deck management with multi-owner support.

Works with Claude Desktop, Pi, Hermes, Cursor, Claude Code, or any MCP client.

---

What you get

28 tools. Full Scryfall API coverage — search, rulings, sets, symbols, catalogs, bulk data, migrations, plus local deck management with multi-owner support, export/import, and card caching.

Area	Tools
Card lookup	search_cards, get_card, autocomplete_card, get_random_cards, get_cards_collection
Card display	Shows all faces (transform/adventure/battle), tokens/related cards, game changer flags, EDHREC rank, purchase links, preview info
Rulings	get_card_rulings
Sets	list_sets, get_set
Symbols	list_card_symbols, parse_mana_cost
Catalogs	get_catalog (creature types, keywords, artists — every canonical list)
API data	list_bulk_data, get_bulk_data, list_card_migrations, get_related_cards
Deck CRUD	create_deck, list_decks, get_deck, update_deck, delete_deck, search_decks
Deck cards	add_card_to_deck, remove_card_from_deck
Deck analysis	analyze_deck, validate_deck
Format rules	get_format_rules (13 formats with per-format validation)
Export/Import	export_deck (MTGA/Archidekt format), import_deck_from_text (bulk add from text)

Decks live as JSON files at ~/.config/scryfall-mcp/decks/. Each deck has an owner field — multiple people can manage their own decks from the same server.

Card data is cached locally at ~/.config/scryfall-mcp/cache/cards/ so repeated lookups (same card, same session or across sessions) cost zero API calls. The cache has a 24-hour TTL.

Both paths live outside your repo clone — updating the code or switching branches won't touch your data.

---

Quick start

git clone <repo-url> scryfall-mcp
cd scryfall-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

That's it. The server starts on stdio, which is what most MCP clients expect.

---

Connecting

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "scryfall": {
      "command": "python3",
      "args": ["/absolute/path/to/scryfall-mcp/server.py"]
    }
  }
}

Pi

Add to your Pi settings.json (global or project-local):

{
  "mcpServers": {
    "scryfall": {
      "command": "python3",
      "args": ["/absolute/path/to/scryfall-mcp/server.py"]
    }
  }
}

Then /reload Pi.

Hermes

Same pattern — point your Hermes MCP config at the server script.

Any MCP client via Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="python3",
    args=["/path/to/scryfall-mcp/server.py"],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("search_cards", {
            "query": "c:red t:instant cmc<=2",
        })
        print(result.content[0].text)

---

Search syntax (the part you'll use most)

Scryfall's search is powerful. Here's the cheat sheet:

c:red                    Color
t:instant                Type
o:"draw a card"          Oracle text
m:{U}{U}                 Mana cost
pow>=4                   Power
tou<=2                   Toughness
s:mkm                    Set code
f:standard               Format legality
id:ub                    Color identity
r:mythic                 Rarity
year:2024                Release year
is:transform             Layout flag
-t:creature              Negation
(t:instant OR t:sorcery) Grouping

Combine freely. c:red t:instant cmc<=1 = cheap red instants.

---

Deck management

Decks are stored as JSON files in ~/.config/scryfall-mcp/decks/. One file per deck.

# Create a deck
python -c "
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run():
    async with stdio_client(StdioServerParameters(command='python3', args=['server.py'])) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            r = await s.call_tool('create_deck', {
                'name': 'My Deck',
                'owner': 'zg',
                'format': 'commander'
            })
            print(r.content[0].text)
asyncio.run(run())
"

Or just use the tools directly from your agent — that's the whole point.

Export to MTG Arena / Archidekt

# Export a deck in MTGA format (importable into Arena, Archidekt, Moxfield)
python -c "
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run():
    async with stdio_client(StdioServerParameters(command='python3', args=['server.py'])) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            r = await s.call_tool('export_deck', {
                'deck_id': '<deck-uuid>',
                'format': 'mtga'
            })
            print(r.content[0].text)
asyncio.run(run())
"

Output:

// My Deck
// Format: commander
// Cards: 100 main + 1 side

// Mainboard
1 Krenko, Mob Boss (JMP) 338
20 Mountain (SLD) 432
4 Lightning Bolt (M10) 123
...

Sideboard
2 Pyroblast (EMA) 141

Import from MTGA text

Paste a deck list into an existing deck:

python -c "... call import_deck_from_text with:
  deck_id: '<deck-uuid>'
  text: |
    4 Lightning Bolt (M10) 123
    20 Mountain
    Sideboard
    2 Disenchant
"

---

Options

python server.py --transport sse --port 8000           # HTTP mode
python server.py --decks-dir ~/Dropbox/my-decks        # Custom deck location

Default transport is stdio. Default deck directory is ~/.config/scryfall-mcp/decks/. Default card cache is ~/.config/scryfall-mcp/cache/.

---

License

MIT. Scryfall data belongs to Scryfall LLC. Magic: The Gathering belongs to Wizards of the Coast.