MTG MCP Servers

A Swift implementation of Magic: The Gathering (MTG) Model Context Protocol (MCP) servers, providing deck management and card search capabilities through the MCP protocol.

Overview

This project provides two MCP servers:

1. MTG Deck Manager (mtg-mcp) - Game state management including deck loading, card drawing, mulligans, and sideboarding
2. Scryfall API Server (scryfall-mcp) - Card information retrieval using the Scryfall API

Both servers implement the MCP protocol for seamless integration with MCP-compatible clients like Claude Desktop.

Features

MTG Deck Manager

• Deck Loading: Parse and load deck lists in various formats
• Game State Management: Track deck, hand, and sideboard contents
• Card Drawing: Draw cards from deck to hand with proper shuffling
• Mulligan Support: London mulligan implementation
• Sideboarding: Swap cards between main deck/sideboard and hand
• Game Reset: Reset to initial game state
• Statistics: Real-time deck and hand statistics

Scryfall API Server

• Card Search: Advanced card search using Scryfall query syntax
• Random Cards: Generate random cards with optional filters
• Name Lookup: Find cards by exact or fuzzy name matching
• Rich Card Data: Complete card information including images, prices, and legalities

Installation

Prerequisites

• Swift 6.2 or later
• macOS 13 or later

Build from Source

# Clone the repository
git clone <repository-url>
cd mtg-mcp

# Build the project
swift build

# Run tests
swift test

Install Executables

# Build in release mode
swift build -c release

# Install to local bin (optional)
cp .build/release/mtg-mcp /usr/local/bin/
cp .build/release/scryfall-mcp /usr/local/bin/

Usage

Running the Servers

MTG Deck Manager Server

# Run with stdio transport (for MCP integration)
swift run mtg-mcp --transport stdio

# Run standalone for testing
swift run mtg-mcp --transport stdio --verbose

Scryfall API Server

# Run with stdio transport
swift run scryfall-mcp --transport stdio

# Run with debug output
swift run scryfall-mcp --transport stdio --verbose

MCP Integration

Claude Desktop Configuration

Add the servers to your Claude Desktop configuration file. The configuration file is typically located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using Swift Run (Development)

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "swift",
      "args": ["run", "mtg-mcp", "--transport", "stdio"],
      "cwd": "/path/to/mtg-mcp"
    },
    "scryfall-api": {
      "command": "swift", 
      "args": ["run", "scryfall-mcp", "--transport", "stdio"],
      "cwd": "/path/to/mtg-mcp"
    },
    "rules-splitter": {
      "command": "swift",
      "args": ["run", "rules-splitter"],
      "cwd": "/path/to/mtg-mcp"
    }
  }
}

Option 2: Using Built Executables (Production)

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "/path/to/.build/release/mtg-mcp",
      "args": ["--transport", "stdio"]
    },
    "scryfall-api": {
      "command": "/path/to/.build/release/scryfall-mcp", 
      "args": ["--transport", "stdio"]
    }
  }
}

Complete Configuration Example

{
  "mcpServers": {
    "mtg-deck-manager": {
      "command": "swift",
      "args": ["run", "mtg-mcp", "--transport", "stdio"],
      "cwd": "/Users/ericraio/mcp/mtg-mcp"
    },
    "scryfall-api": {
      "command": "swift", 
      "args": ["run", "scryfall-mcp", "--transport", "stdio"],
      "cwd": "/Users/ericraio/mcp/mtg-mcp"
    }
  }
}

Production Configuration (Recommended)

First, build the executables:

cd /Users/ericraio/mcp/mtg-mcp
swift build -c release

Then use this configuration:

{
  "mcpServers": {
    "mtg-deck-manager": {

... [View full README on GitHub](https://github.com/ericraio/mtg-mcp#readme)