MTG Commander Deck Analyzer - Decode the secrets of your Commander deck
Project description
Tome - MTG Commander Deck Analyzer
.-+*+=*+=:
:=#@@% :@@%#+:
=@+..-#:.+* .%@+
.@@%*-: .::***@-
=*- .=. =. -*+
.@###::.....:*%@@:
-@@: +* .#-:.+@=
.=#%@@-.#@@#=:
.:=+=++=:.
.--::-=-: :=++*++-:
::-= ...-= =#%%@%=+@%%#=
*= :*: .#%%%%+. -%%%%%*
-= .. - .* *%%%%= -%%%%%+
+. .: .. +: %%%%= -#%%%#
-- -=: .+++==+ *%%% +*.%#%+
+##%%* +%%#%#: *%%- -%%*
:**+-. :=+*= -#%+-...-+%*-
.:---=:: .=+++++-.
.... .:::..
:--++=-:-==. -+-:::::-==.
.*+:=**=:+=.-*- :+:-. .:+=
.####%##==#+. .-= :* :: .. ++
+####*+***-=+- *. *-.%%%*. =%%%= #.
+##=. -+. .=#. **:------:------#
.#* =+. -+= .%%**: -*+ **#%=
.*: :-==- .*%@:. :...%%#-
::.::::=++=. :+-++*#*:+-
..::. ....
..
-@%%%%@@@%%%%%%%%@@@%%%%%# :=#%%%%%%%@@@@@%%%%@+
-@%@@#**+*@@@@@@%++**%@@@% +@%@@@@#++++*#%@@@+
-@%+. :@%%%%@# :*@# +@%%%%@= :*@+
-@: :@%%%%@# +% .:-====. :::::::::. ::::::::: +@%%%%@+ +*
-- :@%%%%@# + -*#%@@@@@% .%*=. .=%@@@@@@%. #@@@@@@%=: +@%%%%@= :
:@%%%%@# =%@@@@#:.%@= *@@@%*. *@%%%%%@# +@%%%%%@# +@%%%%@=
:@%%%%@# #@@%%@# +@ =@%%%@%: *@%%%%%%@* -@%%%%%%@# +@%%%%@=
:@%%%%@# #@%%%%@. .= #@%%%@@: *@%@@%%%%@= :@%@@%%%%@# +@%%%%@%######%*-
:@%%%%@# -@%%%%@# =@%%%%@* *@%%#@%%%%@: %@@*%@%%%@# +@%%%%@%%%%%%#=.
:@%%%%@# +@%%%%@* -@%%%%@% *@%%.*@%@%@%. *@@* %@%%%@# +@%%%%@+
:@%%%%@# +@%%%%@* -@%%%%@% *@%% %@%@%@*+@@% %@%%%@# +@%%%%@=
:@%%%%@# =@%%%%@# =@%%%%@# *@%%. :@@%@%@@%@: .%@%%%@# +@%%%%@= .
:@%%%%@# %@%%%@% *@%%%%@- *@%%. -@%%%%%@- %@%%%@# +@%%%%@+ -+
:@%%%%@# :%@%%%@+ :@%%%@@= *@%%. =@%@%@+ %@%%%@# +@%%%%@= =@+
:@%%%%%% .*@@@%@+ -%@@@@%- *@%%. *@%@# %%%%%@# =@%%%%@+......-+#@@+
.:+@@@@@@@#: :+%@@@@#++*%@@@%*- :%@@@. #@%. @@@@@@%: :#@@@@@@@@@@@@@@@@@@*
:-===========:. .-=+*##**+=: :===== .%: ========- :====================:
Tome is a Python CLI tool that analyzes Commander decklists against best practices, combining rule-based heuristics validation with LLM-powered strategic analysis using the Scryfall API for card data and Claude API for intelligent recommendations.
๐ Decode the secrets of your Commander deck
Features
Deck Analysis
- Decklist Parsing: Supports multiple common formats (Moxfield, MTGO, simple text)
- Moxfield URL Support: Analyze decks directly from Moxfield URLs
- Flexible Deck Size: Analyze incomplete (<100) or oversized (>100) decks with suggestions
- Scryfall Integration: Automatic card data retrieval with 30-day local caching
Heuristic Validation
Checks your deck against established Commander best practices:
- Land count and mana base analysis
- Ramp spells (8-10 recommended)
- Card draw (10+ recommended)
- Removal and board wipes
- Instant-speed interaction
- Graveyard hate
- Color fixing analysis per color
Budget Analysis
- Total deck cost calculation
- Identifies expensive cards (>10% of budget)
- Budget category classification (Ultra-Budget to No-Budget)
LLM Strategic Analysis
- Claude-powered insights on theme, synergies, and improvements
- Interactive chat mode for follow-up questions
- Context-aware recommendations based on your deck's strengths and weaknesses
Interactive Deck Modification
- Add cards:
add Sol Ringoradd Rhystic Study x2 - Remove cards:
remove Temple of the False God - Swap cards:
swap Diabolic Tutor for Demonic Tutor - Batch add/remove: paste multiple card names at once
- Export updated decklist in Moxfield-compatible format
Collection Comparison
- Compare your deck against your existing card collection
- Find budget savings: cards you own that could replace expensive cards
- Find upgrades: better cards you already have
- Interactive swap acceptance:
accept 1oraccept all budget
Beautiful Terminal UI
- Color-coded ASCII art banner
- MTG-themed loading states ("Scrying 3...", "Consulting the council...")
- Formatted tables and visual mana curve
Installation
Quick Install (Recommended)
pip install tome-mtg
Configure API Key
Set your Anthropic API key as an environment variable:
# On Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "your_api_key_here"
# On Windows (Command Prompt)
set ANTHROPIC_API_KEY=your_api_key_here
# On macOS/Linux
export ANTHROPIC_API_KEY=your_api_key_here
Or create a .env file in your working directory:
ANTHROPIC_API_KEY=your_api_key_here
Get your API key from: https://console.anthropic.com/
Install from Source
git clone https://github.com/adrianf/tome-mtg.git
cd tome-mtg
pip install -e .
Usage
Basic Analysis
Analyze a Commander decklist:
tome analyze my_deck.txt
Or using Python module:
python -m tome analyze my_deck.txt
Decklist Format
The analyzer supports multiple formats:
// Commander section (optional)
Commander:
1 Korvold, Fae-Cursed King
// Main deck
Deck:
1 Sol Ring
1x Arcane Signet
1 x Command Tower
Blasphemous Act
// Comments are supported
// Lines starting with // or # are ignored
Supported formats:
1x Card Nameor1 x Card Name1 Card NameCard Name(assumes quantity 1)
Example Output
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Korvold, Fae-Cursed King โ
โ Commander: Korvold, Fae-Cursed King โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
DECK OVERVIEW
Total Cards: 100
Average CMC: 3.2 (non-land)
Color Identity: B/R/G
HEURISTIC CHECKLIST
โโโโโโโโโโโโโโโโฌโโโโโโโโโฌโโโโโโโโโโโฌโโโโโโโโโ
โ Category โ Count โ Expected โ Status โ
โโโโโโโโโโโโโโโโผโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโค
โ Lands โ 38 โ 37-39 โ โ โ
โ Ramp โ 10 โ 8-10 โ โ โ
โ Card Draw โ 9 โ 10+ โ โ โ
โ Removal โ 8 โ ~8 โ โ โ
โ Board Wipes โ 4 โ 3-5 โ โ โ
โโโโโโโโโโโโโโโโดโโโโโโโโโดโโโโโโโโโโโดโโโโโโโโโ
MANA CURVE
0 | โโ 2
1 | โโโโ 4
2 | โโโโโโโโโโโโโโโโ 14
3 | โโโโโโโโโโโโโโโโ 14
4 | โโโโโโโโโโโโ 10
5 | โโโโโโโโ 7
6 | โโโโ 4
7+ | โโ 2
Average CMC: 3.2
STRATEGIC ANALYSIS
**Theme Assessment:**
This is a well-constructed Jund sacrifice/aristocrats deck...
[LLM analysis continues...]
Interactive Mode
Ask questions about your deck (or type 'quit' to exit)
> What should I replace to add more card draw?
[Claude response...]
Collection Comparison
Compare your deck against cards you already own:
tome analyze my_deck.txt --collection my_collection.txt
The collection file uses the same format as deck files. Tome will suggest:
- Budget swaps: expensive cards that can be replaced with cheaper cards you own
- Upgrades: better cards you already have
Interactive Mode
After the analysis, you can ask questions about your deck:
> What cards should I cut for more draw?
> Is this deck too slow?
> Should I add more ramp or cut lands?
> show swaps # Show collection swap suggestions again
> accept 1 # Accept swap suggestion #1
> accept all budget # Accept all high-confidence budget swaps
> quit
Project Structure
mtg/
โโโ tome/ # Main package
โ โโโ __init__.py
โ โโโ __main__.py # Entry point
โ โโโ cli.py # CLI interface
โ โโโ parser.py # Decklist parsing
โ โโโ scryfall_client.py # Scryfall API client
โ โโโ models.py # Data models
โ โโโ heuristics.py # Deck building rules
โ โโโ analyzer.py # Rule-based analysis
โ โโโ llm_analyzer.py # Claude integration
โ โโโ formatter.py # Terminal output
โ โโโ loading_states.py # MTG-themed loading messages
โโโ learnings/ # Deck building guides
โโโ cache/ # Card data cache (auto-generated)
โโโ requirements.txt # Dependencies
โโโ .env # API keys (create from .env.template)
โโโ README.md # This file
Cost Estimates
- Scryfall API: Free (with rate limiting)
- Claude Analysis: ~$0.05 per deck analysis
- Interactive Questions: ~$0.01-0.02 per question
- Total: ~$0.05-0.10 per deck with questions
Troubleshooting
"ANTHROPIC_API_KEY not found"
Make sure you've created the .env file and added your API key.
"Card not found in Scryfall"
The tool uses fuzzy matching, but some card names may not be recognized. Double-check spelling or try the exact name from Scryfall.
Import errors
Make sure you've installed the package correctly:
pip install tome-mtg
Contributing
This is a personal project, but suggestions are welcome! Feel free to fork and customize for your own use.
License
MIT License - Free to use and modify for personal use.
Credits
- Scryfall: Card data provided by Scryfall API (https://scryfall.com/)
- Anthropic: LLM analysis powered by Claude API
- Deck Building Heuristics: Based on guides in the
learnings/folder
Support
For issues or questions, check the troubleshooting section above or review the code comments in each module.
Happy deck building! ๐ด
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
tome_mtg-1.0.0.tar.gz
(56.2 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
tome_mtg-1.0.0-py3-none-any.whl
(56.2 kB
view details)
File details
Details for the file tome_mtg-1.0.0.tar.gz.
File metadata
- Download URL: tome_mtg-1.0.0.tar.gz
- Upload date:
- Size: 56.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
53271aa815709dccdbb6e90b15338777caa825e1cbf77cc7364d38bd920a3589
|
|
| MD5 |
d60ff3b3d52c72a17631f2b0a1e77511
|
|
| BLAKE2b-256 |
c3bbcb929a23a7bd2f4353183c948f1ee2b2e0c8dc8564108497925adc80ee9a
|
File details
Details for the file tome_mtg-1.0.0-py3-none-any.whl.
File metadata
- Download URL: tome_mtg-1.0.0-py3-none-any.whl
- Upload date:
- Size: 56.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.4
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c111ff2eb39e705795f9e97b082714a807d7d62ad471c978968bd2975a850c92
|
|
| MD5 |
abf0f9f5fe432b73a2baf166f5aee2f3
|
|
| BLAKE2b-256 |
2d4c1d7d265902852823e6addef52c136e14bf463bca34774f481db1a4808845
|
