MTG MCP Server

mtg-mcp-server

[CI] [PyPI] [Python 3.12+] [License: MIT] [codecov] [CodeQL] [Smithery] [Dependabot] [uv] [Ruff]

69 tools, 19 prompts, and 21 resources that give AI assistants deep access to Magic: The Gathering -- card data, combos, draft analytics, Commander metagame, competitive constructed, sideboard strategy, deck building, rules engine, and more. Works with Claude Code, Claude Desktop, or any MCP client.

Built on data from Scryfall, Commander Spellbook, 17Lands, EDHREC, Moxfield, Spicerack, and MTGGoldfish. See Data Sources & Attribution for details and usage terms.

Table of Contents

• What You Can Do — example prompts and real tool output
• Install — hosted, Claude Code, Claude Desktop, PyPI, development
• Configuration — environment variables and feature flags
• Tools — all 69 tools across 13 domains
• Architecture — FastMCP 3.x mount system
• Stack — Python 3.12+, FastMCP, httpx, Pydantic
• Development — mise commands for testing, linting, typechecking
• Documentation — cookbook, architecture, tool reference, and more
• Status — current tool/test counts
• Data Sources & Attribution — Scryfall, Spellbook, 17Lands, EDHREC, Moxfield, Spicerack, MTGGoldfish

What You Can Do

Ask your AI assistant questions like these and it will use the MTG tools automatically:

Commander

• "Show me everything about Muldrotha as a commander"
• "What are the best budget upgrades for my Atraxa deck under $5?"
• "Compare Muldrotha vs Meren vs Karador as graveyard commanders"

Draft & Limited

• "What are the best commons in Foundations for draft?"
• "Rank these cards for my draft pack: Bitter Triumph, Monstrous Rage, Torch the Tower"
• "Build a sealed deck from this pool: [list]"

Deck Building

• "Validate my Modern decklist"
• "Suggest a mana base for my 3-color Commander deck"
• "Find cards that synergize with sacrifice themes in Golgari"

Rules

• "How do deathtouch and trample interact?"
• "Resolve this combat scenario: my 3/3 with first strike blocks their 5/5 with trample"

Constructed

• "What does the Modern metagame look like right now?"
• "Show me the stock Boros Energy decklist for Modern"
• "Build me a sideboard for this Pioneer deck"
• "Give me a sideboard guide for my deck against Azorius Control"

See It in Action

"Compare Muldrotha, Meren, and Karador as graveyard commanders"

                     Muldrotha            Meren               KaradorMana Cost            {3}{B}{G}{U}         {2}{B}{G}           {5}{W}{B}{G}Color Identity       BGU (Sultai)         BG (Golgari)        BGW (Abzan)Stats                6/6                  3/4                  3/4EDHREC Rank          #1,137               #1,476              #9,894Total Decks          22,460               19,919              6,305Combo Count          10                   1                   10
Top Staples:  Muldrotha           Spore Frog (+53%), Sakura-Tribe Elder (+36%), Eternal Witness (+27%)  Meren               Spore Frog (+70%), Sakura-Tribe Elder (+55%), Viscera Seer (+52%)  Karador             Karmic Guide (+51%), Satyr Wayfinder (+49%), Sun Titan (+48%)

"What are the best commons in Foundations for draft?"

Foundations (FDN) — PremierDraft · Median GIH WR: 54.7%
Rank  Card               Color  GIH WR   ALSA   IWD      Games1     Bake into a Pie    B      58.4%    3.1    +5.3%    354,7412     Burst Lightning    R      58.2%    3.3    +3.0%    338,8883     Refute             U      58.1%    5.3    +4.3%    321,2804     Stab               B      57.9%    3.4    +4.5%    376,5695     Dazzling Angel     W      57.8%    3.2    +2.4%    317,648
Trap rares: Doubling Season (39.4%), Thousand-Year Storm (35.2%) ...

More examples with real tool output in the Cookbook.

Install

No API keys needed -- all data sources are public.

Hosted (zero setup)

The fastest way to get started. No Python install required. Works on mobile.

Via the UI (Claude Desktop or claude.ai): Settings → Connectors → Add custom connector → paste the URL:

https://mtg-mcp-server.fastmcp.app/mcp

Via config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{  "mcpServers": {    "mtg": {      "type": "url",      "url": "https://mtg-mcp-server.fastmcp.app/mcp"    }  }}

Claude Code

claude mcp add mtg -- uvx mtg-mcp-server

Or via the UI: Settings → MCP Servers → Add server → enter uvx mtg-mcp-server as the command.

Claude Desktop (local)

Runs on your machine. Requires Python 3.12+.

{  "mcpServers": {    "mtg": {      "command": "uvx",      "args": ["mtg-mcp-server"]    }  }}

PyPI

# Run directly (no install)uvx mtg-mcp-server
# Install globallyuv tool install mtg-mcp-server
# Add to a projectuv add mtg-mcp-server

Development

git clone https://github.com/j4th/mtg-mcp-server.gitcd mtg-mcp-servermise install          # Installs Python 3.12, uv, ruff, tymise run setup        # Creates venv, installs dependencies
uv run mtg-mcp-server # Run the server

Claude Code config for local development:

{  "mcpServers": {    "mtg": {      "command": "uv",      "args": ["run", "--directory", "/path/to/mtg-mcp-server", "mtg-mcp-server"]    }  }}

Configuration

All settings use MTG_MCP_ environment variables. Everything works out of the box with sensible defaults.

# Feature flags for optional backendsMTG_MCP_ENABLE_EDHREC=false       # EDHREC (scrapes undocumented endpoints)MTG_MCP_ENABLE_17LANDS=false      # 17Lands (rate-limits aggressively)MTG_MCP_ENABLE_BULK_DATA=false    # Scryfall bulk data (~30MB download on first use)MTG_MCP_ENABLE_RULES=false        # Comprehensive Rules engine
# Pass env vars through uvxuvx --env MTG_MCP_ENABLE_EDHREC=false mtg-mcp-server

See .env.example for all available options including base URLs, rate limits, and cache settings.

Tools

69 tools across 13 domains. See docs/TOOL_DESIGN.md for full input/output details.

Card Data (scryfall_*)

Bulk Data (bulk_*)

Combos (spellbook_*)

Draft Analytics (draft_*)

Commander Metagame (edhrec_*)

Decklists (moxfield_*)

Tournament Data (spicerack_*)

Metagame (goldfish_*)

Commander Workflows

Deck Building

Draft Workflows

Constructed Workflows

Rules Engine

Architecture

Built on FastMCP 3.x. Each data source is an independent sub-server mounted into a single orchestrator:

MTG (orchestrator)├── scryfall (namespace: scryfall_)     -> Scryfall REST API├── spellbook (namespace: spellbook_)   -> Commander Spellbook API├── draft (namespace: draft_)           -> 17Lands data├── edhrec (namespace: edhrec_)         -> EDHREC (scraped, feature-flagged)├── bulk (namespace: bulk_)             -> Scryfall Oracle Cards bulk data├── moxfield (namespace: moxfield_)     -> Moxfield (reverse-engineered, feature-flagged)├── spicerack (namespace: spicerack_)   -> Spicerack tournament API├── goldfish (namespace: goldfish_)     -> MTGGoldfish (scraped, feature-flagged)└── workflows (no namespace)            -> 36 tools (31 composed + 5 rules)

Services are pure async API clients. Providers register MCP tools. Workflows compose across services with partial failure tolerance. See docs/ARCHITECTURE.md for the full picture.

Stack

Development

git clone https://github.com/j4th/mtg-mcp-server.gitcd mtg-mcp-servermise install          # Installs Python, uv, ruff, tymise run setup        # Creates venv, installs dependencies
mise run check        # Full quality gate: lint + typecheck + testsmise run check:quick  # Fast gate: lint + typecheck + affected tests onlymise run test         # All tests with coveragemise run test:quick   # Only tests affected by recent changesmise run lint         # ruff check + format checkmise run typecheck    # ty checkmise run dev          # MCP Inspector for interactive testingmise run fix          # Auto-fix lint and format issues

Documentation

Status

69 tools, 19 prompts, 21 resource templates. 1340 tests at 88% coverage.

Data Sources & Attribution

This project composes data from multiple third-party services:

• Scryfall -- Card database, prices, rulings, search, bulk data (API guidelines)
• Commander Spellbook -- Combo search, bracket estimation (MIT license)
• 17Lands -- Draft card ratings, archetype win rates (usage guidelines)
• EDHREC -- Commander staples, synergy scores (undocumented endpoints, behind feature flag)
• Moxfield -- Public decklists and deck search (reverse-engineered API, behind feature flag)
• Spicerack -- Tournament results and standings (documented API)
• MTGGoldfish -- Competitive metagame data, archetypes, format staples (HTML scraping, behind feature flag)

See THIRD_PARTY_NOTICES.md for full license texts and usage terms.

Disclaimer

mtg-mcp-server is unofficial Fan Content permitted under the Fan Content Policy. Not approved/endorsed by Wizards. Portions of the materials used are property of Wizards of the Coast. © Wizards of the Coast LLC.

License

MIT -- see LICENSE