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.
- MTG Deck Manager(mtg-mcp) - Game state management including deck loading, card drawing, mulligans, and sideboarding
- 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.

- 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

- 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

# Clone the repository git clone <repository-url> cd mtg-mcp # Build the project swift build # Run tests swift test

# 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/

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

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

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

{ "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" } } }

{ "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"] } } }

{ "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" } } }

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

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

- Thecwdpath must point to/Users/ericraio/mcp/mtg-mcpwhere Package.swift exists
- Production builds are faster and more reliable than development builds
- Restart Claude Desktop after updating the configuration
- Restart Claude Desktop
- Start a new conversation
- Test the integrationby asking Claude to:

- "Show me what MTG tools are available"
- "Load a simple MTG deck and draw some cards"
- "Search for Lightning Bolt using Scryfall"
- "Look up MTG rule 100.1"

Once connected, you can use these tools through your MCP client:

# Load a deck upload_deck with deck_list: " Deck 4 Lightning Bolt 4 Counterspell 4 Island 4 Mountain 44 Basic lands Sideboard 2 Negate 1 Spell Pierce " # Draw opening hand draw_card with count: 7 # View your hand view_hand # Get deck statistics view_deck_stats # Play a card play_card with card_name: "Lightning Bolt" # Mulligan to 6 cards mulligan with new_hand_size: 6

# Look up specific rules lookup_rule with rule_number: "100.1" lookup_rule with rule_number: "601.2a" # Search for rules about concepts search_rules with concept: "mulligan" search_rules with concept: "combat" search_rules with keywords: "cast spell" # Get comprehensive explanations explain_concept with concept: "priority" explain_concept with concept: "triggered abilities" explain_concept with concept: "stack"

# Search for cards search_cards with query: "c:red cmc<=3 t:instant" search_cards with query: "t:creature pow>=4" # Get random cards get_random_card get_random_card with query: "c:blue t:counterspell" # Look up specific cards lookup_card_exact with exact: "Lightning Bolt" lookup_card_fuzzy with fuzzy: "Jace Mind Sculptor"

# Sideboarding sideboard_swap with remove_card: "Lightning Bolt" and add_card: "Negate" # Reset game state reset_game # Commander deck setup upload_deck with deck_list: " Commander 1 Atraxa, Praetors' Voice Deck 1 Sol Ring 1 Command Tower 98 Forest "

Here are example prompts you can use with Claude Desktop once the MCP servers are configured:

Load this burn deck and simulate an opening hand: 4 Lightning Bolt 4 Lava Spike 4 Monastery Swiftspear 4 Eidolon of the Great Revel 20 Mountain 4 Fireblast Sideboard: 3 Smash to Smithereens 2 Pyroblast Then draw 7 cards and tell me what kind of opening hand I got.

"Simulate a mulligan decision"

I want to practice mulligan decisions. Load a competitive deck, draw a 7-card opening hand, and tell me if you think I should keep it or mulligan based on the cards drawn.

I'm confused about how the stack works in Magic. Can you: 1. Look up the official rules about the stack 2. Explain how priority works with it 3. Give me an example of how spells and abilities resolve

Look up the official MTG rules about combat damage and explain: - When damage is dealt - How first strike works - What happens with deathtouch - How trample calculates excess damage

"Find cards for my combo deck"

I'm building an artifact combo deck. Search for: 1. Red instants that cost 3 mana or less 2. Artifacts that produce mana 3. Cards that let me draw cards when artifacts enter Show me the most relevant options.

Give me 5 random cards and help me brainstorm a deck theme that could use all of them together.

Quiz me on MTG rules! Look up a random rule number and ask me to explain what it means, then show me the official rule text to check my answer.

Load this deck list and analyze it: - What's the mana curve? - What's the game plan? - What rules should I know for the key cards? - What are potential weaknesses? [paste deck list here]

The deck parser supports multiple formats:

Deck 4 Lightning Bolt 4 Counterspell 20 Island Sideboard 2 Negate 1 Spell Pierce

Commander 1 Atraxa, Praetors' Voice Deck 1 Sol Ring 1 Command Tower 98 Forest

Deck 4 Lightning Bolt (LEA) 4 Counterspell [7ED] 20 Island

4 Lightning Bolt 4 Counterspell 20 Island

mtg-mcp/ ├── Sources/ │ ├── mtg-mcp/ # MTG Deck Manager server │ │ └── mtg_mcp.swift # Main server with rules integration │ ├── scryfall-mcp/ # Scryfall API server │ │ └── scryfall_mcp.swift │ ├── rules-splitter/ # Rules processing tool │ │ └── main.swift # Rule file splitter CLI │ ├── MTGModels/ # Shared models │ │ ├── Card.swift │ │ ├── GameState.swift │ │ ├── ManaCost.swift │ │ └── Rarity.swift │ └── MTGServices/ # Shared services │ ├── DeckParser.swift │ └── RulesService.swift # NEW: Rules lookup service ├── Tests/ │ └── mtg-mcpTests/ # Comprehensive test suite │ ├── CardModelTests.swift │ ├── DeckParserTests.swift │ ├── GameStateTests.swift │ ├── IntegrationTests.swift │ ├── TestDataLoader.swift │ └── TestData/ # Sample deck files ├── rules/ # Generated MTG rules (144 files) │ ├── 100_general.md │ ├── 601_casting_spells.md │ └── ... (142 more rule files) └── Package.swift

- MCP Swift SDK(0.9.0+) - MCP protocol implementation
- SwiftGzip- Compression support for Scryfall API
- ArgumentParser- Command-line argument parsing

# Run all tests swift test # Run specific test suite swift test --filter CardModelTests # Run tests with verbose output swift test --verbose

The project follows Swift best practices:

- Swift actors for thread-safe game state management
- Sendable protocol conformance for concurrent access
- Comprehensive error handling with Result types
- Async/await patterns throughout
- Unit tests with >90% coverage

Game state is managed using Swift'sactorsystem, ensuring thread-safe access to mutable state across concurrent MCP tool calls.

Comprehensive error handling using Swift'sResulttype and custom error types for different failure scenarios.

Both servers implement the MCP protocol using the official Swift SDK, providing:

- Tool registration and discovery
- Request/response handling
- Transport abstraction (stdio, HTTP)
- Proper error propagation

public struct Card: Identifiable, Equatable, Hashable, Codable, Sendable { public let id: String public var name: String public var manaCostString: String public var kind: CardKind public var rarity: Rarity public var typeLine: String public var oracleText: String public var power: String? public var toughness: String? public var loyalty: String? }

public actor GameState { public func loadDeck(_ deckData: DeckData) async public func drawCards(count: Int) async -> [Card] public func playCard(named cardName: String) async -> Card? public func mulligan(newHandSize: Int) async -> [Card] public func sideboardSwap(removeCard: String, addCard: String) async -> (removed: Card?, added: Card?) public func resetGame() async public func getDeckStats() async -> DeckStats public func getHandContents() async -> [String: Int] }

- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request

This project is provided as-is for educational and development purposes.

- MCP Protocol- For the standardized AI integration protocol
- Scryfall API- For comprehensive MTG card data
- swift-landlord- For reference MTG models and game logic
- MCP Swift SDK- For the official Swift MCP implementation

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

Interact & query with Meilisearch (Full-text & semantic search API)

By connecting to Baselight, you can browse, discover, and query 70,000+ datasets and 450+ billion rows directly from your preferred environment—whether you’re building, analysing, or exploring.

A simple MCP server for Elasticsearch, designed for cloud environments where your public key is already authorized.

Search for fish species using the FishBase database. Supports natural language queries in both Japanese and English.

MCP Server to fetch Books, Book Series, and User Books from Hardcover

Provides access to Manticore Search, an open-source database for real-time, full-text search.

MCP Lucene Server is a Model Context Protocol (MCP) server that exposes Apache Lucene's full-text search capabilities through a conversational interface. It allows AI assistants (like Claude) to help users search, index, and manage document collections without requiring technical knowledge of Lucene or search engines.

A server for browsing and searching the official Minecraft Wiki.

A near real-time search server for indexing and querying documents, implemented in Java.

Exposes Lucene-based search indexes to AI assistants through the NRTSearch MCP server.