{
  "markdown": "<!-- mcp-name: io.github.j4th/mtg-mcp-server -->\n# mtg-mcp-server\n\n[![CI](https://github.com/j4th/mtg-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/j4th/mtg-mcp-server/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/mtg-mcp-server)](https://pypi.org/project/mtg-mcp-server/)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)](https://github.com/j4th/mtg-mcp-server)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![codecov](https://codecov.io/gh/j4th/mtg-mcp-server/graph/badge.svg)](https://codecov.io/gh/j4th/mtg-mcp-server)\n[![CodeQL](https://github.com/j4th/mtg-mcp-server/workflows/CodeQL/badge.svg)](https://github.com/j4th/mtg-mcp-server/actions/workflows/codeql.yml)\n[![Smithery](https://smithery.ai/badge/@j4th/mtg-mcp-server)](https://smithery.ai/server/@j4th/mtg-mcp-server)\n[![Dependabot](https://img.shields.io/badge/dependabot-enabled-blue?logo=dependabot)](https://github.com/j4th/mtg-mcp-server/security/dependabot)\n[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n69 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.\n\n> 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.\n\n## Table of Contents\n\n- [What You Can Do](#what-you-can-do) — example prompts and real tool output\n- [Install](#install) — hosted, Claude Code, Claude Desktop, PyPI, development\n- [Configuration](#configuration) — environment variables and feature flags\n- [Tools](#tools) — all 69 tools across 13 domains\n- [Architecture](#architecture) — FastMCP 3.x mount system\n- [Stack](#stack) — Python 3.12+, FastMCP, httpx, Pydantic\n- [Development](#development) — mise commands for testing, linting, typechecking\n- [Documentation](#documentation) — cookbook, architecture, tool reference, and more\n- [Status](#status) — current tool/test counts\n- [Data Sources & Attribution](#data-sources--attribution) — Scryfall, Spellbook, 17Lands, EDHREC, Moxfield, Spicerack, MTGGoldfish\n\n## What You Can Do\n\nAsk your AI assistant questions like these and it will use the MTG tools automatically:\n\n**Commander**\n- \"Show me everything about Muldrotha as a commander\"\n- \"What are the best budget upgrades for my Atraxa deck under $5?\"\n- \"Compare Muldrotha vs Meren vs Karador as graveyard commanders\"\n\n**Draft & Limited**\n- \"What are the best commons in Foundations for draft?\"\n- \"Rank these cards for my draft pack: Bitter Triumph, Monstrous Rage, Torch the Tower\"\n- \"Build a sealed deck from this pool: [list]\"\n\n**Deck Building**\n- \"Validate my Modern decklist\"\n- \"Suggest a mana base for my 3-color Commander deck\"\n- \"Find cards that synergize with sacrifice themes in Golgari\"\n\n**Rules**\n- \"How do deathtouch and trample interact?\"\n- \"Resolve this combat scenario: my 3/3 with first strike blocks their 5/5 with trample\"\n\n**Constructed**\n- \"What does the Modern metagame look like right now?\"\n- \"Show me the stock Boros Energy decklist for Modern\"\n- \"Build me a sideboard for this Pioneer deck\"\n- \"Give me a sideboard guide for my deck against Azorius Control\"\n\n### See It in Action\n\n> \"Compare Muldrotha, Meren, and Karador as graveyard commanders\"\n\n```\n                     Muldrotha            Meren               Karador\nMana Cost            {3}{B}{G}{U}         {2}{B}{G}           {5}{W}{B}{G}\nColor Identity       BGU (Sultai)         BG (Golgari)        BGW (Abzan)\nStats                6/6                  3/4                  3/4\nEDHREC Rank          #1,137               #1,476              #9,894\nTotal Decks          22,460               19,919              6,305\nCombo Count          10                   1                   10\n\nTop Staples:\n  Muldrotha           Spore Frog (+53%), Sakura-Tribe Elder (+36%), Eternal Witness (+27%)\n  Meren               Spore Frog (+70%), Sakura-Tribe Elder (+55%), Viscera Seer (+52%)\n  Karador             Karmic Guide (+51%), Satyr Wayfinder (+49%), Sun Titan (+48%)\n```\n\n> \"What are the best commons in Foundations for draft?\"\n\n```\nFoundations (FDN) — PremierDraft · Median GIH WR: 54.7%\n\nRank  Card               Color  GIH WR   ALSA   IWD      Games\n1     Bake into a Pie    B      58.4%    3.1    +5.3%    354,741\n2     Burst Lightning    R      58.2%    3.3    +3.0%    338,888\n3     Refute             U      58.1%    5.3    +4.3%    321,280\n4     Stab               B      57.9%    3.4    +4.5%    376,569\n5     Dazzling Angel     W      57.8%    3.2    +2.4%    317,648\n\nTrap rares: Doubling Season (39.4%), Thousand-Year Storm (35.2%) ...\n```\n\nMore examples with real tool output in the [Cookbook](docs/COOKBOOK.md).\n\n## Install\n\nNo API keys needed -- all data sources are public.\n\n### Hosted (zero setup)\n\nThe fastest way to get started. No Python install required. Works on mobile.\n\n**Via the UI** (Claude Desktop or claude.ai): Settings → Connectors → Add custom connector → paste the URL:\n\n```\nhttps://mtg-mcp-server.fastmcp.app/mcp\n```\n\n**Via config file** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"mtg\": {\n      \"type\": \"url\",\n      \"url\": \"https://mtg-mcp-server.fastmcp.app/mcp\"\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add mtg -- uvx mtg-mcp-server\n```\n\nOr via the UI: Settings → MCP Servers → Add server → enter `uvx mtg-mcp-server` as the command.\n\n### Claude Desktop (local)\n\nRuns on your machine. Requires Python 3.12+.\n\n```json\n{\n  \"mcpServers\": {\n    \"mtg\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mtg-mcp-server\"]\n    }\n  }\n}\n```\n\n### PyPI\n\n```bash\n# Run directly (no install)\nuvx mtg-mcp-server\n\n# Install globally\nuv tool install mtg-mcp-server\n\n# Add to a project\nuv add mtg-mcp-server\n```\n\n### Development\n\n```bash\ngit clone https://github.com/j4th/mtg-mcp-server.git\ncd mtg-mcp-server\nmise install          # Installs Python 3.12, uv, ruff, ty\nmise run setup        # Creates venv, installs dependencies\n\nuv run mtg-mcp-server # Run the server\n```\n\nClaude Code config for local development:\n\n```json\n{\n  \"mcpServers\": {\n    \"mtg\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/mtg-mcp-server\", \"mtg-mcp-server\"]\n    }\n  }\n}\n```\n\n## Configuration\n\nAll settings use `MTG_MCP_` environment variables. Everything works out of the box with sensible defaults.\n\n```bash\n# Feature flags for optional backends\nMTG_MCP_ENABLE_EDHREC=false       # EDHREC (scrapes undocumented endpoints)\nMTG_MCP_ENABLE_17LANDS=false      # 17Lands (rate-limits aggressively)\nMTG_MCP_ENABLE_BULK_DATA=false    # Scryfall bulk data (~30MB download on first use)\nMTG_MCP_ENABLE_RULES=false        # Comprehensive Rules engine\n\n# Pass env vars through uvx\nuvx --env MTG_MCP_ENABLE_EDHREC=false mtg-mcp-server\n```\n\nSee `.env.example` for all available options including base URLs, rate limits, and cache settings.\n\n## Tools\n\n69 tools across 13 domains. See [docs/TOOL_DESIGN.md](docs/TOOL_DESIGN.md) for full input/output details.\n\n### Card Data (`scryfall_*`)\n\n| Tool | Description |\n|------|-------------|\n| `search_cards` | Search using full Scryfall syntax (`f:commander id:sultai t:creature`) |\n| `card_details` | Full card data by exact or fuzzy name |\n| `card_price` | Current USD, EUR, and foil prices |\n| `card_rulings` | Official rulings and clarifications |\n| `set_info` | Set metadata by code |\n| `whats_new` | Recently released or previewed cards |\n\n### Bulk Data (`bulk_*`)\n\n| Tool | Description |\n|------|-------------|\n| `card_lookup` | Rate-limit-free card lookup by exact name |\n| `card_search` | Search by name, type, or oracle text |\n| `format_legality` | Check if a card is legal in a format |\n| `format_search` | Search for cards legal in a specific format |\n| `format_staples` | Top-played cards in a format by EDHREC rank |\n| `ban_list` | Banned and restricted cards for a format |\n| `card_in_formats` | Card legality across all formats |\n| `random_card` | Random card, optionally filtered by format or type |\n| `similar_cards` | Find cards similar by type, keywords, or mana cost |\n\n### Combos (`spellbook_*`)\n\n| Tool | Description |\n|------|-------------|\n| `find_combos` | Search for combos by card name and color identity |\n| `combo_details` | Step-by-step combo instructions by ID |\n| `find_decklist_combos` | Find combos present in a decklist |\n| `estimate_bracket` | Estimate Commander bracket for a decklist |\n\n### Draft Analytics (`draft_*`)\n\n| Tool | Description |\n|------|-------------|\n| `card_ratings` | Win rates and draft data for cards in a set (17Lands) |\n| `archetype_stats` | Win rates by color pair for a set |\n\n### Commander Metagame (`edhrec_*`)\n\n| Tool | Description |\n|------|-------------|\n| `commander_staples` | Most-played cards for a commander with synergy scores |\n| `card_synergy` | Synergy data for a card with a specific commander |\n\n### Decklists (`moxfield_*`)\n\n| Tool | Description |\n|------|-------------|\n| `decklist` | Fetch a full decklist by deck ID or URL |\n| `deck_info` | Deck metadata (name, format, author, dates) |\n| `search_decks` | Search public decks by format, keyword, or sort order |\n| `user_decks` | List a user's public decks |\n\n### Tournament Data (`spicerack_*`)\n\n| Tool | Description |\n|------|-------------|\n| `recent_tournaments` | Recent tournaments for a competitive format |\n| `tournament_results` | Full standings for a specific tournament |\n| `format_decklists` | Top-finishing decklists across recent tournaments |\n\n### Metagame (`goldfish_*`)\n\n| Tool | Description |\n|------|-------------|\n| `metagame` | Current metagame breakdown for a competitive format |\n| `archetype_list` | Sample decklist for an archetype |\n| `format_staples` | Most-played cards in a format with deck inclusion % |\n| `deck_price` | Estimated paper price for an archetype deck |\n\n### Commander Workflows\n\n| Tool | Description |\n|------|-------------|\n| `commander_overview` | Full commander profile from all sources |\n| `evaluate_upgrade` | Assess whether a card is worth adding to a deck |\n| `card_comparison` | Compare 2-5 cards side-by-side for a commander |\n| `budget_upgrade` | Budget-constrained upgrade suggestions ranked by synergy/$ |\n| `commander_comparison` | Compare 2-5 commanders head-to-head |\n| `color_identity_staples` | Top-played cards across all commanders in a color identity |\n\n### Deck Building\n\n| Tool | Description |\n|------|-------------|\n| `theme_search` | Find cards matching a mechanical or tribal theme |\n| `build_around` | Detect synergies from key cards and find complements |\n| `complete_deck` | Gap analysis and suggestions for a partial decklist |\n| `tribal_staples` | Best cards for a creature type in a color identity |\n| `precon_upgrade` | Analyze a precon and suggest swap pairs |\n| `suggest_cuts` | Identify the weakest cards to cut from a decklist |\n| `deck_analysis` | Full decklist health check (curve, colors, combos, budget) |\n| `deck_validate` | Validate a decklist against format construction rules |\n| `suggest_mana_base` | Suggest lands based on color pip distribution |\n| `price_comparison` | Compare prices across multiple cards |\n\n### Draft Workflows\n\n| Tool | Description |\n|------|-------------|\n| `draft_pack_pick` | Rank cards in a draft pack using 17Lands data |\n| `set_overview` | Top commons/uncommons and trap rares for a format |\n| `sealed_pool_build` | Suggest the best 40-card builds from a sealed pool |\n| `draft_signal_read` | Detect open colors from draft picks |\n| `draft_log_review` | Pick-by-pick review of a completed draft with grade |\n\n### Constructed Workflows\n\n| Tool | Description |\n|------|-------------|\n| `rotation_check` | Standard rotation status and rotating cards |\n| `metagame_snapshot` | Tiered metagame breakdown with prices |\n| `archetype_decklist` | Stock decklist for a competitive archetype |\n| `archetype_comparison` | Compare 2-4 archetypes side-by-side |\n| `format_entry_guide` | Beginner guide for entering a competitive format |\n| `suggest_sideboard` | 15-card sideboard suggestions for a deck |\n| `sideboard_guide` | In/out plan for a specific matchup |\n| `sideboard_matrix` | Sideboard matrix across common matchups |\n\n### Rules Engine\n\n| Tool | Description |\n|------|-------------|\n| `rules_lookup` | Look up rules by number or keyword |\n| `keyword_explain` | Explain a keyword with rules and example cards |\n| `rules_interaction` | How two mechanics interact with rule citations |\n| `rules_scenario` | Rules framework for a game scenario |\n| `combat_calculator` | Step-by-step combat phases with keyword interactions |\n\n## Architecture\n\nBuilt on **FastMCP 3.x**. Each data source is an independent sub-server mounted into a single orchestrator:\n\n```\nMTG (orchestrator)\n├── scryfall (namespace: scryfall_)     -> Scryfall REST API\n├── spellbook (namespace: spellbook_)   -> Commander Spellbook API\n├── draft (namespace: draft_)           -> 17Lands data\n├── edhrec (namespace: edhrec_)         -> EDHREC (scraped, feature-flagged)\n├── bulk (namespace: bulk_)             -> Scryfall Oracle Cards bulk data\n├── moxfield (namespace: moxfield_)     -> Moxfield (reverse-engineered, feature-flagged)\n├── spicerack (namespace: spicerack_)   -> Spicerack tournament API\n├── goldfish (namespace: goldfish_)     -> MTGGoldfish (scraped, feature-flagged)\n└── workflows (no namespace)            -> 36 tools (31 composed + 5 rules)\n```\n\nServices 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.\n\n## Stack\n\n| | |\n|---|---|\n| Runtime | Python 3.12+, uv |\n| MCP | FastMCP 3.2.x |\n| HTTP | httpx (async) |\n| Validation | Pydantic v2 |\n| Logging | structlog |\n| Tooling | mise, ruff, ty (Astral) |\n| Testing | pytest, respx, pytest-asyncio |\n| HTML parsing | selectolax |\n\n## Development\n\n```bash\ngit clone https://github.com/j4th/mtg-mcp-server.git\ncd mtg-mcp-server\nmise install          # Installs Python, uv, ruff, ty\nmise run setup        # Creates venv, installs dependencies\n\nmise run check        # Full quality gate: lint + typecheck + tests\nmise run check:quick  # Fast gate: lint + typecheck + affected tests only\nmise run test         # All tests with coverage\nmise run test:quick   # Only tests affected by recent changes\nmise run lint         # ruff check + format check\nmise run typecheck    # ty check\nmise run dev          # MCP Inspector for interactive testing\nmise run fix          # Auto-fix lint and format issues\n```\n\n## Documentation\n\n| Doc | What it covers |\n|-----|----------------|\n| [COOKBOOK.md](docs/COOKBOOK.md) | Usage recipes -- Commander, draft, deck building, rules workflows |\n| [TOOL_DESIGN.md](docs/TOOL_DESIGN.md) | Full reference for all 69 tools, 19 prompts, 21 resources |\n| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Technical architecture, FastMCP patterns, design decisions |\n| [SERVICE_CONTRACTS.md](docs/SERVICE_CONTRACTS.md) | API endpoints, rate limits, response shapes per backend |\n| [DATA_SOURCES.md](docs/DATA_SOURCES.md) | All data sources with auth, stability, and access patterns |\n| [CACHING_DESIGN.md](docs/CACHING_DESIGN.md) | TTL cache strategy and Scryfall bulk data design |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, TDD workflow, code style, PR process |\n| [CHANGELOG.md](CHANGELOG.md) | Version history in Keep a Changelog format |\n\n## Status\n\n69 tools, 19 prompts, 21 resource templates. 1340 tests at 88% coverage.\n\n| Phase | What | Status |\n|-------|------|--------|\n| 0 | Project scaffold | Done |\n| 1 | Scryfall backend (4 tools) | Done |\n| 2 | Spellbook + 17Lands + EDHREC backends (9 tools) | Done |\n| 3 | Workflow tools -- commander, draft, deck (4 tools) | Done |\n| 4 | TTL caching + Scryfall bulk data provider (2 tools) | Done |\n| 5 | Analysis & comparison workflows, prompts, resources (4 tools) | Done |\n| Branch A | Structured output, rules engine, validation tools (17 tools) | Done |\n| Branch B | Format workflows -- deck building, commander depth, limited, constructed (11 tools) | Done |\n| Moxfield | Moxfield decklist provider (4 tools) | Done |\n| Spicerack | Tournament results provider (3 tools) | Done |\n| MTGGoldfish | Metagame data provider (4 tools) | Done |\n| v2.3.0 | Metagame workflows, sideboard tools, Moxfield search (9 tools) | Done |\n\n## Data Sources & Attribution\n\nThis project composes data from multiple third-party services:\n\n- **[Scryfall](https://scryfall.com)** -- Card database, prices, rulings, search, bulk data ([API guidelines](https://scryfall.com/docs/api))\n- **[Commander Spellbook](https://commanderspellbook.com)** -- Combo search, bracket estimation ([MIT license](https://github.com/SpaceCowMedia/commander-spellbook-backend))\n- **[17Lands](https://www.17lands.com)** -- Draft card ratings, archetype win rates ([usage guidelines](https://www.17lands.com/usage_guidelines))\n- **[EDHREC](https://edhrec.com)** -- Commander staples, synergy scores (undocumented endpoints, behind feature flag)\n- **[Moxfield](https://www.moxfield.com)** -- Public decklists and deck search (reverse-engineered API, behind feature flag)\n- **[Spicerack](https://spicerack.gg)** -- Tournament results and standings ([documented API](https://docs.spicerack.gg))\n- **[MTGGoldfish](https://www.mtggoldfish.com)** -- Competitive metagame data, archetypes, format staples (HTML scraping, behind feature flag)\n\nSee [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for full license texts and usage terms.\n\n## Disclaimer\n\nmtg-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. &copy; Wizards of the Coast LLC.\n\n## License\n\nMIT -- see [LICENSE](LICENSE)\n",
  "bytes": 18577,
  "sha": "518813b49076cbb4e9249807a81ec4a639d09c3632d405c9bcc80765c13a3b51",
  "repo_slug": "j4th/mtg-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_j4th_mtg_mcp_server_79021378/readme"
}