AImaginationLab/magic-the-gathering-toolkit

Magic: The Gathering Toolkit

A comprehensive toolkit for Magic: The Gathering players featuring a terminal UI deck builder, card collection manager, synergy finder, and MCP server for AI integration. Search 33,000+ cards, import your collection, discover deck and synergy recommendations, browse artist profiles, and more.

Features

• Card Search - Search 33,000+ cards with 15+ filters (name, colors, type, CMC, keywords, format, rarity, set)
• Artwork Browser - High-resolution card art with gallery, focus, and compare views
• Deck Builder - Full deck management with mana curve, color balance, and format validation
• Collection Tracker - Track owned cards, wishlist, multiple printings, foils
• Synergy Finder - Discover card synergies and combos based on keywords, types, and abilities
• Recommendations - Get personalized card suggestions for your decks based on your collection
• Price Tracking - Current USD/EUR prices from Scryfall
• Artist Portfolios - Browse cards by artist
• MCP Server - Integrate with MCP capable client applications for AI-powered deck building assistance

Packages

This is a UV workspace with three packages:

Requirements

• Python 3.11+
• uv package manager
• Terminal with true color support (iTerm2, Kitty, Windows Terminal, etc.)

Quick Start

# Clone and install
git clone https://github.com/AImaginationLab/magic-the-gathering-toolkit.git
cd magic-the-gathering-toolkit
uv sync

# Launch the terminal UI
uv run mtg-spellbook

MTG Spellbook (Terminal UI)

A themed terminal interface for card lookups, artwork browsing, deck building, and synergy discovery.

uv run mtg-spellbook

Search Syntax

Type directly in the search bar search followed by:

Combine filters: search t:creature c:r cmc:3 f:standard

Keyboard Shortcuts

The terminal UI is designed to be navigated through with keyboard shortcuts, tabs + arrows, or with your mouse.

Card View Modes

• Gallery View (g) - Filmstrip of all printings with prices
• Focus View (f) - Full card display with metadata
• Compare View (c) - Side-by-side comparison (up to 4 cards)

MCP Server

Integrate with MCP-compatible clients for AI-powered assistance.

uv run mtg-mcp

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mtg": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/magic-the-gathering-toolkit", "mtg-mcp"]
    }
  }
}

Example Prompts

• "Build me a budget Mono-Red Commander deck under $50"
• "What are the best counterspells in Modern?"
• "Find cards that synergize with Rhystic Study"
• "Is this deck legal in Pioneer?" (paste your decklist)

Available Tools

Data Sources

The unified database is downloaded automatically with uv run create-datasources. To refresh:

uv run create-datasources          # Re-download database
uv run create-datasources clear-cache  # Clear cached data

Environment Variables

MTG_DB_PATH=resources/mtg.sqlite
LOG_LEVEL=INFO

# Cache settings
CACHE_MAX_SIZE=1000
CACHE_TTL_SECONDS=3600

# Image cache settings
# Disk cache limit in MB (default 1024 = 1GB, stores ~1000 card images as PNG)
IMAGE_CACHE_MAX_MB=1024
# Number of images to keep in memory for fast access
IMAGE_MEMORY_CACHE_COUNT=20

# Data cache settings (printings, synergies - stored as compressed JSON)
# Disk cache limit in MB (default 100MB, gzip compressed)
DATA_CACHE_MAX_MB=100

Development

uv sync --all-extras    # Install dev dependencies
uv run pytest packages/ # Run tests
uv run ruff check packages/  # Lint
uv run ruff format packages/ # Format
uv run mypy packages/        # Type check

Magic: The Gathering Toolkit 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.

Data used in this project obtained from MTGJson, Scryfall, 17lands and CommanderSpellbook.