mtg-mcp-server 1.0.0

Unified MCP server providing Magic: The Gathering data to AI assistants

mtg-mcp-server

A Magic: The Gathering MCP server for AI assistants. Search cards, analyze draft formats, explore Commander combos, evaluate deck upgrades — all from Claude Code, Claude Desktop, or any MCP client.

Built on data from Scryfall, Commander Spellbook, 17Lands, EDHREC, and MTGJSON. See Data Sources & Attribution for details and usage terms.

What It Does

Card Data (via Scryfall) — Search the full MTG card database, check prices, look up rulings, verify format legality.

Combo Discovery (via Commander Spellbook) — Find combos for any commander or card, estimate deck bracket/power level.

Draft Analytics (via 17Lands) — Card win rates by set and archetype, format speed analysis, draft pick recommendations.

Commander Metagame (via EDHREC) — Top cards by commander, synergy scores, inclusion rates, average decklists.

Composed Workflows — Higher-level tools that cross-reference multiple sources: commander overviews, upgrade evaluations, sealed pool analysis, deck audits.

Install

Requires Python 3.12+. No API keys needed — all data sources are public.

# Run directly with uvx (no install needed)
uvx mtg-mcp-server

# Or install globally
uv tool install mtg-mcp-server

# Or install in a project
uv add mtg-mcp-server

Connect to Claude Code

claude mcp add mtg -- uvx mtg-mcp-server

Or add to your MCP config (.mcp.json or ~/.claude/settings.json):

{
  "mcpServers": {
    "mtg": {
      "command": "uvx",
      "args": ["mtg-mcp-server"]
    }
  }
}

Then in Claude Code:

> Search for Sultai creatures with CMC 3 or less that are legal in Commander
> What combos does Muldrotha enable?
> Show me draft ratings for the top BG commons in Lorwyn Eclipsed
> Evaluate adding Spore Frog to my Muldrotha deck, cutting Eternal Skylord

Connect to Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mtg": {
      "command": "uvx",
      "args": ["mtg-mcp-server"]
    }
  }
}

Configuration

All settings use MTG_MCP_ environment variables with sensible defaults. No configuration required to get started.

# Disable optional backends
MTG_MCP_ENABLE_EDHREC=false    # EDHREC scrapes undocumented endpoints
MTG_MCP_ENABLE_17LANDS=false   # 17Lands rate-limits aggressively
MTG_MCP_ENABLE_MTGJSON=false   # MTGJSON downloads ~100MB bulk file on first use

# Pass env vars to uvx
uvx --env MTG_MCP_ENABLE_EDHREC=false mtg-mcp-server

See .env.example for all available options.

Local Install (from source)

If you want to run from a local checkout instead of PyPI:

git clone https://github.com/j4th/mtg-mcp-server.git
cd mtg-mcp-server
mise install && mise run setup

# Run the server directly
uv run mtg-mcp-server

# Or use uvx with a local path
uvx --from /path/to/mtg-mcp-server mtg-mcp-server

Claude Code config for a local install:

{
  "mcpServers": {
    "mtg": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mtg-mcp-server", "mtg-mcp-server"]
    }
  }
}

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 + format + typecheck + test
mise run test         # pytest with coverage
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

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)
├── mtgjson (namespace: mtgjson_)       → MTGJSON bulk data
└── workflows (no namespace)            → Composed tools: commander_overview, etc.

Services are pure async API clients. Providers register MCP tools. Workflows compose across services. See docs/ARCHITECTURE.md for the full picture.

Stack

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

Status

All planned phases are complete: 23 tools, 4 prompts, 6 resources, 374 tests at 92% 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 + MTGJSON bulk provider (2 tools)	Done
5	Analysis & comparison workflows, prompts, resources (4 tools)	Done

Data Sources & Attribution

This project composes data from multiple third-party services:

• Scryfall — Card database, prices, rulings, search (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)
• MTGJSON — Bulk card data for rate-limit-free lookups (MIT license)

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