MTG MCP Server
Magic: The Gathering card search, combo lookup, draft analytics, and Commander tools.
Open source Open in the app JSON README (API)
About
Magic: The Gathering card search, combo lookup, draft analytics, and Commander tools.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- j4th
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.0.0
- Stars
- 20
- Forks
- 4
- Open pull requests
- 4
- Last push
- 2026-06-24T00:54:49Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:12
- Updated
- 2026-08-29 04:00:12
- Origin id
io.github.j4th/mtg-mcp-server
README
<!-- mcp-name: io.github.j4th/mtg-mcp-server -->
# 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)