mtg-mcp-server
Smithery
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
uvx mtg-mcp-server
uv tool install mtg-mcp-server
uv add mtg-mcp-server
Development
git clone https://github.com/j4th/mtg-mcp-server.git
cd mtg-mcp-server
mise install
mise run setup
uv run mtg-mcp-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.
MTG_MCP_ENABLE_EDHREC=false
MTG_MCP_ENABLE_17LANDS=false
MTG_MCP_ENABLE_BULK_DATA=false
MTG_MCP_ENABLE_RULES=false
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.
69 tools across 13 domains. See docs/TOOL_DESIGN.md for full input/output details.
Card Data (scryfall_*)
Tool Description search_cardsSearch using full Scryfall syntax (f:commander id:sultai t:creature) card_detailsFull card data by exact or fuzzy name card_priceCurrent USD, EUR, and foil prices card_rulingsOfficial rulings and clarifications set_infoSet metadata by code whats_newRecently released or previewed cards
Bulk Data (bulk_*)
Tool Description card_lookupRate-limit-free card lookup by exact name card_searchSearch by name, type, or oracle text format_legalityCheck if a card is legal in a format format_searchSearch for cards legal in a specific format format_staplesTop-played cards in a format by EDHREC rank ban_listBanned and restricted cards for a format card_in_formatsCard legality across all formats random_cardRandom card, optionally filtered by format or type similar_cardsFind cards similar by type, keywords, or mana cost
Combos (spellbook_*)
Tool Description find_combosSearch for combos by card name and color identity combo_detailsStep-by-step combo instructions by ID find_decklist_combosFind combos present in a decklist estimate_bracketEstimate Commander bracket for a decklist
Draft Analytics (draft_*)
Tool Description card_ratingsWin rates and draft data for cards in a set (17Lands) archetype_statsWin rates by color pair for a set
Tool Description commander_staplesMost-played cards for a commander with synergy scores card_synergySynergy data for a card with a specific commander
Decklists (moxfield_*)
Tool Description decklistFetch a full decklist by deck ID or URL deck_infoDeck metadata (name, format, author, dates) search_decksSearch public decks by format, keyword, or sort order user_decksList a user's public decks
Tournament Data (spicerack_*)
Tool Description recent_tournamentsRecent tournaments for a competitive format tournament_resultsFull standings for a specific tournament format_decklistsTop-finishing decklists across recent tournaments
Tool Description metagameCurrent metagame breakdown for a competitive format archetype_listSample decklist for an archetype format_staplesMost-played cards in a format with deck inclusion % deck_priceEstimated paper price for an archetype deck
Commander Workflows
Tool Description commander_overviewFull commander profile from all sources evaluate_upgradeAssess whether a card is worth adding to a deck card_comparisonCompare 2-5 cards side-by-side for a commander budget_upgradeBudget-constrained upgrade suggestions ranked by synergy/$ commander_comparisonCompare 2-5 commanders head-to-head color_identity_staplesTop-played cards across all commanders in a color identity
Deck Building
Tool Description theme_searchFind cards matching a mechanical or tribal theme build_aroundDetect synergies from key cards and find complements complete_deckGap analysis and suggestions for a partial decklist tribal_staplesBest cards for a creature type in a color identity precon_upgradeAnalyze a precon and suggest swap pairs suggest_cutsIdentify the weakest cards to cut from a decklist deck_analysisFull decklist health check (curve, colors, combos, budget) deck_validateValidate a decklist against format construction rules suggest_mana_baseSuggest lands based on color pip distribution price_comparisonCompare prices across multiple cards
Draft Workflows
Tool Description draft_pack_pickRank cards in a draft pack using 17Lands data set_overviewTop commons/uncommons and trap rares for a format sealed_pool_buildSuggest the best 40-card builds from a sealed pool draft_signal_readDetect open colors from draft picks draft_log_reviewPick-by-pick review of a completed draft with grade
Constructed Workflows
Tool Description rotation_checkStandard rotation status and rotating cards metagame_snapshotTiered metagame breakdown with prices archetype_decklistStock decklist for a competitive archetype archetype_comparisonCompare 2-4 archetypes side-by-side format_entry_guideBeginner guide for entering a competitive format suggest_sideboard15-card sideboard suggestions for a deck sideboard_guideIn/out plan for a specific matchup sideboard_matrixSideboard matrix across common matchups
Rules Engine
Tool Description rules_lookupLook up rules by number or keyword keyword_explainExplain a keyword with rules and example cards rules_interactionHow two mechanics interact with rule citations rules_scenarioRules framework for a game scenario combat_calculatorStep-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
mise run setup
mise run check
mise run check:quick
mise run test
mise run test :quick
mise run lint
mise run typecheck
mise run dev
mise run fix
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