mtg by guzmonne - MCP Server

MTG CLI

A powerful command-line interface for Magic: The Gathering card data with AI integration capabilities.

Overview

MTG CLI is a comprehensive command-line tool that provides access to Magic: The Gathering card data through multiple APIs. Built with Rust for performance and reliability, it offers both traditional CLI functionality and modern AI integration through the Model Context Protocol (MCP).

Features

Core Functionality

Multiple Search Engines: Support for MTG API, Wizards' Gatherer, and Scryfall APIs
Advanced Card Search: Search with filters for name, colors, type, rarity, set, mana cost, and more
Set Browsing: Explore Magic sets and generate virtual booster packs
Type Information: Access comprehensive card types, subtypes, supertypes, and game formats
Shell Completions: Auto-completion support for Bash, Zsh, Fish, PowerShell, and Elvish
High Performance: Async operations with built-in caching and timeout controls
MTG Arena Companion (macOS/Windows only): Real-time log monitoring and game state tracking

AI Integration (MCP)

MCP Server: Model Context Protocol server for seamless AI assistant integration
Rich Data Access: 20,000+ Magic cards with full details and metadata
Interactive Tools: 8 comprehensive tools for card lookup, search, and deck analysis
Pre-built Prompts: Templates for common Magic-related AI tasks
Multiple Transports: STDIO and SSE support for different integration needs

Output & Usability

Formatted Tables: Clean, readable output with proper alignment
Pagination: Handle large result sets efficiently
Environment Variables: Configurable defaults for common options
Verbose Mode: Detailed logging and debugging information

Installation

Pre-built Binaries

Download pre-built binaries for your operating system from GitHub Releases. Binaries are available for:

Linux (x86_64, ARM64)
macOS (Intel, Apple Silicon)
Windows (x86_64)

Build from Source

Prerequisites:

Rust (1.70 or later) - Install Rust
Git

Steps:

Clone and build:

git clone https://github.com/cloudbridgeuy/mtg.git
cd mtg
cargo build --bin mtg --release

Install globally (optional):

cargo install --bin mtg --path crates/mtg

Verify installation:

./target/release/mtg --version
# or if installed globally:
mtg --version

Quick Start

Command Overview

The CLI provides access to three main APIs:

api - MTG API for basic card, set, and type queries
scryfall - Scryfall API for advanced search with flexible syntax
gatherer - Wizards' Gatherer database for official card data

Basic Usage

# MTG API - Basic card search
mtg api cards search "Lightning Bolt"
mtg api sets list --page-size 10
mtg api types list

# Scryfall API - Advanced search
mtg scryfall search "c:blue t:instant mv<=3" --pretty
mtg scryfall named "Lightning Bolt" --pretty
mtg scryfall collector ktk 96 --pretty

# Gatherer API - Official Wizards data
mtg gatherer search --name "Lightning Bolt" --rarity "Common"
mtg gatherer search --colors "Red" --type "Instant"

# Generate booster pack
mtg api sets booster "KTK"

Set Up Shell Completions

# Bash
mtg completions generate bash > ~/.local/share/bash-completion/completions/mtg

# Zsh
mtg completions generate zsh > ~/.zsh/completions/_mtg

# Fish
mtg completions generate fish > ~/.config/fish/completions/mtg.fish

# PowerShell
mtg completions generate powershell >> $PROFILE

MCP Server for AI Integration

# Start MCP server (STDIO transport)
mtg mcp

# Start with SSE transport for web applications
mtg mcp sse --host 127.0.0.1 --port 3000

# With custom configuration
mtg --api-base-url https://api.magicthegathering.io/v1 --timeout 60 mcp

Usage Guide

Global Options

All commands support these global options:

--api-base-url <URL> - Override the default MTG API URL
--timeout <SECONDS> - Set request timeout (default: 30)
--verbose - Enable verbose output
--help - Show help information
--version - Show version information

Environment Variables

Configure defaults using environment variables:

export MTG_API_BASE_URL="https://api.magicthegathering.io/v1"
export MTG_TIMEOUT=60
export MTG_VERBOSE=1

Card Commands

# Basic search
mtg api cards search "Lightning"

# Exact name matching
mtg api cards search "Lightning Bolt" --exact

# Advanced filtering
mtg api cards list --colors "Red,Blue" --type "Creature" --cmc 4

# Get specific card by ID
mtg api cards get 409574

# Search with pagination
mtg api cards search "Dragon" --page 2 --page-size 20

Set Commands

# List all sets
mtg api sets list

# Search sets by name
mtg api sets search "Zendikar"

# Get specific set information
mtg api sets get "KTK"

# Generate booster pack
mtg api sets booster "ISD"

Type Commands

# List all card types
mtg api types list

# Get subtypes
mtg api types subtypes

# Get supertypes
mtg api types supertypes

# Get game formats
mtg api types formats

Completion Commands

# Generate completions for your shell
mtg completions generate bash
mtg completions generate zsh
mtg completions generate fish
mtg completions generate powershell
mtg completions generate elvish

MCP Server for AI Integration

The MTG CLI includes a powerful Model Context Protocol (MCP) server that enables AI assistants to access Magic: The Gathering data seamlessly.

Key Features

Rich Data Access: 20,000+ Magic cards with full details and metadata
Interactive Tools: 8 comprehensive tools for card lookup, search, and deck analysis
Multiple APIs: Access to MTG API, Scryfall, and Gatherer through unified interface
Advanced Search: Complex queries with 15+ sort options and filtering
Deck Analysis: Comprehensive statistics including mana curve and format legality
Multiple Transports: STDIO (default) and SSE support for different integration needs

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "mtg": {
      "command": "/path/to/mtg",
      "args": ["mcp"],
      "env": {
        "MTG_TIMEOUT": "60"
      }
    }
  }
}

Available MCP Components

Resources: Access to complete card, set, and type databases
Tools: Interactive functions for searching, analysis, and booster generation
Prompts: Pre-built templates for card analysis, deck building, and comparisons

Examples

Advanced Card Searches

# Find expensive red creatures
mtg api cards list --colors "Red" --type "Creature" --cmc 6 --rarity "Mythic Rare"

# Search for artifacts from specific set
mtg api cards list --type "Artifact" --set "KTK" --page-size 50

# Find cards legal in Modern format
mtg api cards list --format "Modern" --rarity "Rare"

Set Analysis

# Research Khans of Tarkir
mtg api sets get "KTK"

# Generate multiple booster packs
for i in {1..3}; do
  echo "=== Booster Pack $i ==="
  mtg api sets booster "KTK"
  echo
done

Deck Building Research

# Find all Dragons
mtg api cards list --subtype "Dragon" --page-size 100

# Research tribal strategies
mtg api types subtypes | grep -i "warrior\|wizard\|goblin"

# Check format legality
mtg api types formats

Development

Building

# Development build
cargo build

# Release build with optimizations
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- api cards search "Lightning Bolt"

Project Structure

mtg/
├── crates/
│   └── mtg/           # Main CLI application
├── docs/              # Comprehensive documentation
├── xtask/             # Build automation
├── Cargo.toml         # Workspace configuration
└── README.md          # This file

Dependencies

Key dependencies include:

clap - Command-line argument parsing
clap_complete - Shell completion generation
tokio - Async runtime
reqwest - HTTP client for API calls
serde - JSON serialization/deserialization
prettytable - Formatted table output
rmcp - Model Context Protocol server
color-eyre - Enhanced error reporting

Documentation

Comprehensive documentation is available in the directory:

CLI Usage

- Installation and basic usage
- MTG API card search techniques
- Set browsing and booster generation
- Type system and format queries
- Official Wizards search functionality
- Powerful Scryfall search engine
- Completion setup for all shells

MCP Integration

- AI assistant integration guide
- Getting the MCP server running
- Interactive card search tools for AI assistants
- Available data resources
- Pre-built prompt templates

Troubleshooting

Common Issues

Network Timeouts:

# Increase timeout
mtg --timeout 120 api cards search "Complex Query"

API Rate Limiting:

Use smaller page sizes
Add delays between requests
The CLI includes built-in rate limiting

Connection Issues:

# Test API connectivity
curl -s "https://api.magicthegathering.io/v1/cards?pageSize=1"

# Check with verbose output
mtg --verbose api cards search "test"

Shell Completions Not Working:

# Verify completion file exists
ls -la ~/.local/share/bash-completion/completions/mtg

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

Debug Mode

Enable detailed debugging:

export RUST_LOG=debug
export RUST_BACKTRACE=1
mtg --verbose api cards search "Lightning Bolt"

Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, improving documentation, or enhancing the AI integration capabilities.

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Add tests if applicable
Run the test suite: cargo test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow Rust best practices and idioms
Add tests for new functionality
Update documentation for user-facing changes
Ensure shell completions work with new commands
Test MCP integration if modifying server functionality

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Magic: The Gathering API for providing comprehensive card data
Model Context Protocol for enabling AI integration
The Rust community for excellent crates and tooling
Wizards of the Coast for creating Magic: The Gathering

guzmonne/mtg

MTG CLI

Overview

Features

Core Functionality

AI Integration (MCP)

Output & Usability

Installation

Pre-built Binaries

Build from Source

Quick Start

Command Overview

Basic Usage

Set Up Shell Completions

MCP Server for AI Integration

Usage Guide

Global Options

Environment Variables

Card Commands

Set Commands

Type Commands

Completion Commands

MCP Server for AI Integration

Key Features

Claude Desktop Integration

Available MCP Components

Examples

Advanced Card Searches

Set Analysis

Deck Building Research

Development

Building

Project Structure

Dependencies

Documentation

CLI Usage

MCP Integration

Troubleshooting

Common Issues

Debug Mode

Contributing

Getting Started

Development Guidelines

License

Acknowledgments

Links