mtg-mcp-server

mtg-mcp-server

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               Karador
Mana 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/4
EDHREC Rank          #1,137               #1,476              #9,894
Total Decks          22,460               19,919              6,305
Combo 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      Games
1     Bake into a Pie    B      58.4%    3.1    +5.3%    354,741
2     Burst Lightning    R      58.2%    3.3    +3.0%    338,888
3     Refute             U      58.1%    5.3    +4.3%    321,280
4     Stab               B      57.9%    3.4    +4.5%    376,569
5     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 globally
uv tool install mtg-mcp-server

# Add to a project
uv add mtg-mcp-server

Development

git clone https://github.com/j4th/mtg-mcp-server.git
cd mtg-mcp-server
mise install          # Installs Python 3.12, uv, ruff, ty
mise 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 backends
MTG_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 uvx
uvx --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_*)

Tool	Description
search_cards	Search using full Scryfall syntax (f:commander id:sultai t:creature)
card_details	Full card data by exact or fuzzy name
card_price	Current USD, EUR, and foil prices
card_rulings	Official rulings and clarifications
set_info	Set metadata by code
whats_new	Recently released or previewed cards

Bulk Data (bulk_*)

Tool	Description
card_lookup	Rate-limit-free card lookup by exact name
card_search	Search by name, type, or oracle text
format_legality	Check if a card is legal in a format
format_search	Search for cards legal in a specific format
format_staples	Top-played cards in a format by EDHREC rank
ban_list	Banned and restricted cards for a format
card_in_formats	Card legality across all formats
random_card	Random card, optionally filtered by format or type
similar_cards	Find cards similar by type, keywords, or mana cost

Combos (spellbook_*)

Tool	Description
find_combos	Search for combos by card name and color identity
combo_details	Step-by-step combo instructions by ID
find_decklist_combos	Find combos present in a decklist
estimate_bracket	Estimate Commander bracket for a decklist

Draft Analytics (draft_*)

Tool	Description
card_ratings	Win rates and draft data for cards in a set (17Lands)
archetype_stats	Win rates by color pair for a set

Commander Metagame (edhrec_*)

Tool	Description
commander_staples	Most-played cards for a commander with synergy scores
card_synergy	Synergy data for a card with a specific commander

Decklists (moxfield_*)

Tool	Description
decklist	Fetch a full decklist by deck ID or URL
deck_info	Deck metadata (name, format, author, dates)
search_decks	Search public decks by format, keyword, or sort order
user_decks	List a user's public decks

Tournament Data (spicerack_*)

Tool	Description
recent_tournaments	Recent tournaments for a competitive format
tournament_results	Full standings for a specific tournament
format_decklists	Top-finishing decklists across recent tournaments

Metagame (goldfish_*)

Tool	Description
metagame	Current metagame breakdown for a competitive format
archetype_list	Sample decklist for an archetype
format_staples	Most-played cards in a format with deck inclusion %
deck_price	Estimated paper price for an archetype deck

Commander Workflows

Tool	Description
commander_overview	Full commander profile from all sources
evaluate_upgrade	Assess whether a card is worth adding to a deck
card_comparison	Compare 2-5 cards side-by-side for a commander
budget_upgrade	Budget-constrained upgrade suggestions ranked by synergy/$
commander_comparison	Compare 2-5 commanders head-to-head
color_identity_staples	Top-played cards across all commanders in a color identity

Deck Building

Tool	Description
theme_search	Find cards matching a mechanical or tribal theme
build_around	Detect synergies from key cards and find complements
complete_deck	Gap analysis and suggestions for a partial decklist
tribal_staples	Best cards for a creature type in a color identity
precon_upgrade	Analyze a precon and suggest swap pairs
suggest_cuts	Identify the weakest cards to cut from a decklist
deck_analysis	Full decklist health check (curve, colors, combos, budget)
deck_validate	Validate a decklist against format construction rules
suggest_mana_base	Suggest lands based on color pip distribution
price_comparison	Compare prices across multiple cards

Draft Workflows

Tool	Description
draft_pack_pick	Rank cards in a draft pack using 17Lands data
set_overview	Top commons/uncommons and trap rares for a format
sealed_pool_build	Suggest the best 40-card builds from a sealed pool
draft_signal_read	Detect open colors from draft picks
draft_log_review	Pick-by-pick review of a completed draft with grade

Constructed Workflows

Tool	Description
rotation_check	Standard rotation status and rotating cards
metagame_snapshot	Tiered metagame breakdown with prices
archetype_decklist	Stock decklist for a competitive archetype
archetype_comparison	Compare 2-4 archetypes side-by-side
format_entry_guide	Beginner guide for entering a competitive format
suggest_sideboard	15-card sideboard suggestions for a deck
sideboard_guide	In/out plan for a specific matchup
sideboard_matrix	Sideboard matrix across common matchups

Rules Engine

Tool	Description
rules_lookup	Look up rules by number or keyword
keyword_explain	Explain a keyword with rules and example cards
rules_interaction	How two mechanics interact with rule citations
rules_scenario	Rules framework for a game scenario
combat_calculator	Step-by-step combat phases with keyword interactions

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

Runtime	Python 3.12+, uv
MCP	FastMCP 3.2.x
HTTP	httpx (async)
Validation	Pydantic v2
Logging	structlog
Tooling	mise, ruff, ty (Astral)
Testing	pytest, respx, pytest-asyncio
HTML parsing	selectolax

Development

git clone https://github.com/j4th/mtg-mcp-server.git
cd mtg-mcp-server
mise install          # Installs Python, uv, ruff, ty
mise run setup        # Creates venv, installs dependencies

mise run check        # Full quality gate: lint + typecheck + tests
mise run check:quick  # Fast gate: lint + typecheck + affected tests only
mise run test         # All tests with coverage
mise run test:quick   # Only tests affected by recent changes
mise run lint         # ruff check + format check
mise run typecheck    # ty check
mise run dev          # MCP Inspector for interactive testing
mise run fix          # Auto-fix lint and format issues

Documentation

Doc	What it covers
COOKBOOK.md	Usage recipes -- Commander, draft, deck building, rules workflows
TOOL_DESIGN.md	Full reference for all 69 tools, 19 prompts, 21 resources
ARCHITECTURE.md	Technical architecture, FastMCP patterns, design decisions
SERVICE_CONTRACTS.md	API endpoints, rate limits, response shapes per backend
DATA_SOURCES.md	All data sources with auth, stability, and access patterns
CACHING_DESIGN.md	TTL cache strategy and Scryfall bulk data design
CONTRIBUTING.md	Development setup, TDD workflow, code style, PR process
CHANGELOG.md	Version history in Keep a Changelog format

Status

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

Phase	What	Status
0	Project scaffold	Done
1	Scryfall backend (4 tools)	Done
2	Spellbook + 17Lands + EDHREC backends (9 tools)	Done
3	Workflow tools -- commander, draft, deck (4 tools)	Done
4	TTL caching + Scryfall bulk data provider (2 tools)	Done
5	Analysis & comparison workflows, prompts, resources (4 tools)	Done
Branch A	Structured output, rules engine, validation tools (17 tools)	Done
Branch B	Format workflows -- deck building, commander depth, limited, constructed (11 tools)	Done
Moxfield	Moxfield decklist provider (4 tools)	Done
Spicerack	Tournament results provider (3 tools)	Done
MTGGoldfish	Metagame data provider (4 tools)	Done
v2.3.0	Metagame workflows, sideboard tools, Moxfield search (9 tools)	Done

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