万智牌指挥官MCP服务

MTG Commander MCP Server

A Model Context Protocol (MCP) server for Magic: The Gathering Commander/EDH. Provides 19 tools across 7 data sources for card lookup, deck building, price comparison, rules reference, and personal-collection workflows.

Data Sources

Tools

EDHRec

• edhrec_commander_recommendations - Top cards for a commander by category with synergy scores and inclusion rates. Supports theme filtering.
• edhrec_commander_combos - Popular combos with results, popularity percentage, and bracket data.
• edhrec_commander_themes - Available archetypes/themes with slugs and deck counts.
• edhrec_top_cards - Top EDH cards by time period (year/month/week).
• edhrec_search_commanders - Browse commanders by color identity.

Commander Spellbook

• spellbook_combos - Search combos by card name(s) and/or color identity (e.g. ub), most popular first. Returns the cards, what the combo produces, step-by-step instructions, and a link.

Scryfall

• scryfall_card - Full card data including oracle text, mana cost, type, legality, pricing, and image. Handles double-faced and split cards.
• scryfall_search - Search using Scryfall syntax (e.g. c:ug type:creature cmc<=3).
• scryfall_rulings - Official rulings for a card.

Deck Tools

• import_deck - Import a deck from an Archidekt or Moxfield URL.
• analyze_deck - Import and analyze a deck: mana curve, color distribution, type breakdown, mana base evaluation, EDHRec-based card suggestions, and a bracket report (Game Changers from Scryfall, Commander Spellbook combos in the deck and one card away, and a minimum_bracket floor; mass land denial / extra-turn cards are checked for Archidekt decks).
• build_deck - Build a full 100-card Commander deck from a card name. Supports budget tiers and theme filtering. Includes the same bracket report. If the card isn't a commander, suggests commanders that use it.

Pricing

• price_deck - Price a deck from Archidekt/Moxfield on both TCGPlayer and Card Kingdom. Compares total cost and card availability with a recommendation. Uses Scryfall's batched /cards/collection endpoint plus 8-way concurrent EDHRec lookups, so a 100-card deck typically prices in ~10–20 s (down from 2–3 minutes in earlier versions). Note: a deck full of edge-case prints can produce a brief request burst that briefly trips Scryfall's per-IP rate limiter; if a follow-on Scryfall-backed tool (scryfall_card, scryfall_search, scryfall_rulings) returns "Scryfall rate limit exceeded after retries", wait ~30 s and retry. (The internal throttle race that used to amplify this was fixed in 0.2.0.)
• refresh_pricing_data - Refresh the local MTGJSON pricing cache (~132 MB daily prices snapshot + ~150 MB identifiers map). Call once after install for fast buy-list pricing; subsequent calls auto-refresh on staleness. ~60–90s first download, ~30s daily refresh.
• pricing_cache_status - Read-only inspection of the MTGJSON cache state (sizes, ages, freshness flag).

Collection (Delver Lens)

• import_collection - Import a Magic collection from a Delver Lens CSV export, or any compatible preset (Moxfield, TCGPlayer, Deckbox, MTGstand). Accepts a local file path, http(s):// URL, or pasted CSV text. Auto-detects column variants (Name/Card Name, Quantity/Count, Set Code/Edition, Foil/Printing, Scryfall ID). Resolves names via Scryfall (preferring scryfall_id when present). Pass persist=True to store as the active collection on disk for the rest of the collection tools.
• collection_summary - Stats on the active collection: unique cards, total quantity, estimated USD value (TCGPlayer), color identity breakdown, and top sets.
• compute_card_allocation - Given a list of Archidekt/Moxfield deck URLs (and/or an Archidekt username for auto-discovery), shows what's committed to existing decks vs free to use, and flags over_committed cards (used in more decks than you own).
• pull_and_buy_lists - The headline workflow tool. Given a new deck (URL or pasted decklist) plus your existing decks, returns a pull list (cards to physically pull from the free pool of your collection) and a priced buy list (TCGPlayer USD) for the rest. Skips basic lands by default (include_basics=True to include them).

Why CSV?

mtg.delver.dev/collection is a Firebase-authed single-page app — there is no public API and the dashboard URL isn't shareable. Delver's documented, stable export surface is CSV (or the proprietary .dlens SQLite backup; not currently supported). To use the collection tools:

1. In Delver Lens or the web app, export your collection as CSV.
2. Pick a preset (any of Delver-native, Moxfield, TCGPlayer, Deckbox, or MTGstand will auto-detect).
3. Pass the file path / URL / pasted text to import_collection(source=..., persist=True).

Rules

• mtg_rules - Search the MTG Comprehensive Rules by keyword or rule number. Covers 3,100+ rules and 730+ glossary entries. Auto-updates when Wizards publishes new rules.

Installation

Requires uv:

git clone https://github.com/GrooGruxKing27/mtg-commander-MCP.git
cd mtg-commander-MCP
uv sync

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mtg-commander": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mtg-commander-MCP",
        "--no-editable",
        "mtg-commander-mcp"
      ]
    }
  }
}

Use the absolute path to uv (find it with which uv) — Claude Desktop doesn't inherit your shell PATH. The --no-editable flag sidesteps a ModuleNotFoundError caused by editable-install .pth files under Python 3.14.

Restart Claude Desktop to pick up the new server.

Claude Code Setup

Add to your Claude Code settings or .claude/settings.json:

{
  "mcpServers": {
    "mtg-commander": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mtg-commander-MCP",
        "--no-editable",
        "mtg-commander-mcp"
      ]
    }
  }
}

Troubleshooting

• ModuleNotFoundError: No module named 'mtg_commander_mcp' — make sure --no-editable is in your args (see above). Python 3.14 breaks editable installs that rely on .pth files.
• Operation not permitted when launching — if your config invokes a shell-script wrapper (e.g. run.sh) that lives inside ~/Documents, macOS TCC will block the sandboxed Claude Desktop from executing it. Use the uv run command directly as shown above, or move the repo outside ~/Documents (e.g. ~/src/).

Testing

Run the MCP Inspector:

uv run mcp dev src/mtg_commander_mcp/server.py

Budget Tiers (build_deck)

Color Identity Filters (edhrec_search_commanders)

Mono: white, blue, black, red, green, colorless

Two-color: azorius, dimir, rakdos, gruul, selesnya, orzhov, izzet, golgari, boros, simic

Three-color: esper, grixis, jund, naya, bant, abzan, jeskai, sultai, mardu, temur

Five-color: five-color

Dependencies

• mcp[cli] - Model Context Protocol SDK
• httpx - Async HTTP client
• cloudscraper - Cloudflare bypass for Moxfield

License

MIT. See also CHANGELOG.md for release notes.