# mtg-mcp-server [](https://github.com/j4th/mtg-mcp-server/actions/workflows/ci.yml) [](https://pypi.org/project/mtg-mcp-server/) [](https://github.com/j4th/mtg-mcp-server) [](LICENSE) [](https://codecov.io/gh/j4th/mtg-mcp-server) [](https://github.com/j4th/mtg-mcp-server/actions/workflows/codeql.yml) [](https://smithery.ai/server/@j4th/mtg-mcp-server) [](https://github.com/j4th/mtg-mcp-server/security/dependabot) [](https://github.com/astral-sh/uv) [](https://github.com/astral-sh/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](https://scryfall.com), [Commander Spellbook](https://commanderspellbook.com), [17Lands](https://www.17lands.com), [EDHREC](https://edhrec.com), [Moxfield](https://www.moxfield.com), [Spicerack](https://spicerack.gg), and [MTGGoldfish](https://www.mtggoldfish.com). See [Data Sources & Attribution](#data-sources--attribution) for details and usage terms. ## Table of Contents - [What You Can Do](#what-you-can-do) — example prompts and real tool output - [Install](#install) — hosted, Claude Code, Claude Desktop, PyPI, development - [Configuration](#configuration) — environment variables and feature flags - [Tools](#tools) — all 69 tools across 13 domains - [Architecture](#architecture) — FastMCP 3.x mount system - [Stack](#stack) — Python 3.12+, FastMCP, httpx, Pydantic - [Development](#development) — mise commands for testing, linting, typechecking - [Documentation](#documentation) — cookbook, architecture, tool reference, and more - [Status](#status) — current tool/test counts - [Data Sources & Attribution](#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](docs/COOKBOOK.md). ## 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): ```json { "mcpServers": { "mtg": { "type": "url", "url": "https://mtg-mcp-server.fastmcp.app/mcp" } } } ``` ### Claude Code ```bash 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+. ```json { "mcpServers": { "mtg": { "command": "uvx", "args": ["mtg-mcp-server"] } } } ``` ### PyPI ```bash # 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 ```bash 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: ```json { "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. ```bash # 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](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](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 ```bash 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](docs/COOKBOOK.md) | Usage recipes -- Commander, draft, deck building, rules workflows | | [TOOL_DESIGN.md](docs/TOOL_DESIGN.md) | Full reference for all 69 tools, 19 prompts, 21 resources | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Technical architecture, FastMCP patterns, design decisions | | [SERVICE_CONTRACTS.md](docs/SERVICE_CONTRACTS.md) | API endpoints, rate limits, response shapes per backend | | [DATA_SOURCES.md](docs/DATA_SOURCES.md) | All data sources with auth, stability, and access patterns | | [CACHING_DESIGN.md](docs/CACHING_DESIGN.md) | TTL cache strategy and Scryfall bulk data design | | [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, TDD workflow, code style, PR process | | [CHANGELOG.md](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](https://scryfall.com)** -- Card database, prices, rulings, search, bulk data ([API guidelines](https://scryfall.com/docs/api)) - **[Commander Spellbook](https://commanderspellbook.com)** -- Combo search, bracket estimation ([MIT license](https://github.com/SpaceCowMedia/commander-spellbook-backend)) - **[17Lands](https://www.17lands.com)** -- Draft card ratings, archetype win rates ([usage guidelines](https://www.17lands.com/usage_guidelines)) - **[EDHREC](https://edhrec.com)** -- Commander staples, synergy scores (undocumented endpoints, behind feature flag) - **[Moxfield](https://www.moxfield.com)** -- Public decklists and deck search (reverse-engineered API, behind feature flag) - **[Spicerack](https://spicerack.gg)** -- Tournament results and standings ([documented API](https://docs.spicerack.gg)) - **[MTGGoldfish](https://www.mtggoldfish.com)** -- Competitive metagame data, archetypes, format staples (HTML scraping, behind feature flag) See [THIRD_PARTY_NOTICES.md](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](https://company.wizards.com/en/legal/fancontentpolicy). 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](LICENSE)