MTG Commander Deck Builder

A workspace for building validated, 100-card Commander (EDH) decks — backed by a local mirror of Scryfall's full card data, a research → build → simulate → validate workflow, and complete gameplay docs per deck.

The orchestration guide lives in CLAUDE.md; the deep reference and a fully worked example are in sotd/.

What's here

Path	Contents
mtg-card-db/	Local SQLite mirror of Scryfall's oracle_cards export, with CLI tools for card-pool research, color-identity validation, and decklist checking. See mtg-card-db/AGENTS.md.
sotd/	Worked example deck — The Serpent Society (deathtouch/poison). Includes the deep build reference in sotd/CLAUDE.md.
loot/	Worked example deck — Loot.
CLAUDE.md	The build workflow: phases, deliverables, and format rules.

Setup

Requires Python 3.10+.

# 1. Install dependencies
cd mtg-card-db
pip install -r requirements.txt

# 2. Build the card database (~166MB download → ~42MB SQLite, ~12s)
python scripts/sync.py

Note: the card database (mtg-card-db/data/) is not committed to the repo — it's large and fully regenerable. Run sync.py once after cloning to create it. Scryfall publishes a fresh bulk export daily; re-run sync.py anytime to refresh.

Scryfall asks for a reachable contact in the request User-Agent. Set one (optional):

export SCRYFALL_CONTACT="you@example.com"   # or a URL; defaults to a generic value

Using the card database

All commands run from mtg-card-db/. Full reference: mtg-card-db/AGENTS.md.

# Look up a single card (color identity, oracle text, etc.)
python scripts/query.py card --name "Ophiomancer" --output json

# Research a card pool by colors / type / keyword, ranked by EDHREC staple-ness
python scripts/query.py cards --colors BG --type creature --keyword deathtouch --limit 30 --output json

# Validate a finished 100-card list (singleton, color identity, no silver-border)
python scripts/validate.py --decklist sotd/decklist_import.txt --commander "The Serpent Society" --output json

Run it in Docker (optional, auto-refreshes daily)

cd mtg-card-db
docker compose up -d   # builds the DB and re-syncs every day at 03:00

Tests

cd mtg-card-db
pytest