Mtg Mcp

MTG Commander MCP Server

[](https://github.com/nathanmartins/mtg-mcp/actions/workflows/ci.yaml) [](https://github.com/nathanmartins/mtg-mcp/actions/workflows/cd.yaml) [](https://github.com/nathanmartins/mtg-mcp/actions/workflows/lint.yaml)

A Model Context Protocol (MCP) server for Magic: The Gathering Commander format, providing comprehensive card information, rulings, pricing, deck validation tools, and multi-platform deck importing.

[](https://goreportcard.com/report/github.com/nathanmartins/mtg-mcp) [](https://github.com/nathanmartins/mtg-mcp/blob/main/LICENSE) [](https://github.com/nathanmartins/mtg-mcp/releases/latest) [](https://github.com/nathanmartins/mtg-mcp/blob/main/go.mod)

Features

Tools (AI-Callable Functions)

Scryfall Card Data (7 tools)

1. search_cards – Search for MTG cards using Scryfall search syntax

• Supports advanced queries (colors, types, abilities, etc.)
• Returns up to 50 results with full card details
• Includes Commander legality status

1. getcarddetails – Get detailed information about a specific card

• Oracle text and rules
• Mana cost, type, power/toughness
• Color identity
• Format legalities across all formats
• Artist and set information

1. checkcommanderlegality – Check if a card is legal in Commander

• Shows legality status across all formats
• Clear indication of banned/legal/not legal status
• Quick format validation

1. getcardrulings – Get official card rulings and clarifications

• Official WotC rulings
• Dates and sources for each ruling
• Comprehensive rules clarifications

1. getcardprice – Get current card pricing

• USD and EUR prices from Scryfall
• BRL (Brazilian Real) pricing via real-time currency conversion
• Supports both regular and foil versions
• Optional set-specific pricing

1. getbannedlist – Get the current Commander banned list

• Real-time data from Scryfall
• 85+ banned cards (updated automatically)
• Complete list with card names

1. validate_deck – Validate a Commander deck

• 100-card deck size check
• Singleton rule verification (no duplicates except basics)
• Commander legality check
• Color identity validation
• Supports JSON array or text format decklists

Moxfield Integration (3 tools)

1. getmoxfielddeck – Fetch the complete deck from Moxfield

• Accepts deck URL or public ID
• Full decklist with card types organized
• Deck metadata (views, likes, comments, author)
• Commanders, mainboard, sideboard, maybeboard
• Last updated timestamp

1. getmoxfielduser_decks – Get user's deck list from Moxfield

• List all decks for a Moxfield user
• Paginated results (up to 100 per page)
• Deck summaries with views and likes
• Format and public URL for each deck

1. searchmoxfielddecks – Search for decks on Moxfield by commander

• Search by commander name
• Filter by format (commander, standard, modern, etc.)
• Sort by updated, views, or likes
• Paginated results (up to 100 per page)
• Returns deck metadata with views, likes, and URLs

Archidekt Integration (3 tools)

1. getarchidektdeck – Fetch a complete deck from Archidekt

• Accepts deck URL or numeric ID (e.g., https://archidekt.com/decks/12345 or 12345)
• Full decklist organised by a card type
• Commander(s) identified via the premier category flag
• Deck metadata (format, owner, views, EDH bracket, last updated)
• Direct link back to the Archidekt deck page
• Optional lands_only flag — returns only land cards, ideal for landbase comparisons

without the token overhead of a full decklist

1. getarchidektuser_decks – Get a user's public decks from Archidekt

• List all public decks for any Archidekt username
• Paginated results with direct deck URLs
• Format name, view count, and last-updated date for each deck

1. searcharchidektdecks – Search public Commander decks by commander name

• Required commander parameter (card name, e.g. "Atraxa, Praetors' Voice")
• Optional bracket filter (1–4; omit searching all brackets)
• Optional limit (default: 10, max: 20)
• Results sorted by view count descending
• Each result includes deck name, author, view count, EDH bracket, last updated, and direct URL

EDHREC Meta Data (2 tools)

1. getedhrecrecommendations – Get EDHREC recommendations for a commander

• High-synergy cards with synergy scores
• Most popular cards by inclusion rate
• New cards trending for the commander
• Card categories (creatures, instants, artifacts, etc.)
• Deck count and meta-statistics
• Salt scores for controversial cards

1. getedhreccombos – Get popular combos for color combinations

• Combo cards and prerequisites
• Combo results (e.g., "Infinite mana", "Win the game")
• Usage statistics and percentages
• Ranked by popularity
• Color identity filtering (w/u/b/r/g)

Resources (Data Sources)

1. commander://rules – Complete Commander format rules

• Deck construction guidelines
• Gameplay rules
• Winning conditions
• Official sources

1. commander://banned-list - JSON-formatted banned list

• Real-time data
• Card names, types, and mana costs
• Total count of banned cards

Installation

Prerequisites

• Go 1.26 or later
• Internet connection (for Scryfall API and currency conversion)

Building from Source

# Clone or navigate to the project directory
cd mtg-mcp

# Install dependencies
go mod tidy

# Build the MCP server
go build -o mtg-mcp

The compiled binary mtg-mcp is an MCP server for use with Claude Desktop or other MCP clients.

Usage

Running as an MCP Server

The server uses stdio transport for communication with MCP clients like Claude Desktop:

./mtg-mcp

Connecting to Claude Desktop

To use this server with Claude Desktop, add the following configuration to your claude_desktop_config.json:

Location:

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

Configuration:

{
  "mcpServers": {
    "mtg-commander": {
      "command": "/absolute/path/to/mtg-mcp/mtg-mcp"
    }
  }
}

Replace /absolute/path/to/mtg-mcp/ with the actual path to the binary.

After adding the configuration, restart Claude Desktop.

Connecting to Claude Code (Global Configuration)

To make this server available globally in Claude Code across all projects:

Option 1: Using the CLI (Recommended)

claude mcp add --transport stdio mtg-commander /absolute/path/to/mtg-mcp/mtg-mcp --scope user

Option 2: Manual Configuration

Edit the global MCP configuration file:

File location:

• macOS: ~/.claude/servers.json
• Windows: %APPDATA%\ClaudeCode\servers.json
• Linux: ~/.config/ClaudeCode/servers.json

Configuration:

{
  "mcpServers": {
    "mtg-commander": {
      "command": "/absolute/path/to/mtg-mcp/mtg-mcp",
      "args": [],
      "transport": "stdio"
    }
  }
}

Verify installation:

claude mcp list

You should see mtg-commander in the list of available servers.

Example Queries

Once connected to Claude Desktop, you can ask questions like:

Card Data:

• "Search for blue counterspells in Commander"
• "Is Mana Crypt legal in Commander?"
• "What are the official rulings for Doubling Season?"
• "How much does Sol Ring cost in BRL?"
• "Show me the current Commander banned list"
• "Validate my Commander deck with Atraxa as commander"

Moxfield:

• "Fetch this Moxfield deck: "
• "Show me decks by user JohnDoe on Moxfield"
• "What's in the mainboard of Moxfield deck xyz789?"
• "Search Moxfield for top Atraxa, Praetors' Voice decks"
• "Find the most popular Thrasios decks on Moxfield sorted by views"

Archidekt:

• "Fetch this Archidekt deck: "
• "Show me decks by user NorwegianWhaler on Archidekt"
• "What's the commander and decklist for Archidekt deck 67890?"

EDHREC:

• "What are the best cards for Atraxa, Praetors' Voice, according to EDHREC?"
• "Show me popular combos in Dimir colors (ub)"
• "What are high-synergy cards for Meren of Clan Nel Toth?"
• "Get me the top 5-color combos for WUBRG"

Architecture

Technology Stack

• Language: Go 1.26+
• MCP Framework: mark3labs/mcp-go
• Card Data API: Scryfall API

via go-scryfall

• Currency Conversion: Frankfurter API (free, no API key)
• Logging: zerolog for structured JSON logging
• Transport: stdio (Model Context Protocol)

Data Sources

1. Card Data: Scryfall API

• Updated daily
• Complete MTG card database
• Includes rulings, legalities, and pricing
• Rate-limited to 10 requests/second (built into a client)

1. Commander Rules: Official format rules embedded in server

• Source:
• Format managed by Wizards of the Coast

1. Pricing:

• Base prices: Scryfall (USD/EUR)
• BRL conversion: Real-time exchange rates via Frankfurter API
• Note: Prices are indicative and may not reflect Brazilian market conditions

1. Moxfield: Unofficial API ()

• Deck data and user profiles
• Metadata including views, likes, comments
• Note: No official public API; be respectful of rate limits
• Contact for authorized access

1. Archidekt: Open public API ()

• Deck data including full card lists and categories
• Owner, format, EDH bracket, and view count metadata
• Note: API is open for read access; credit deck creators when publishing data
• No API key required

1. EDHREC: Unofficial JSON endpoints ()

• Card recommendations and synergies
• Meta-statistics and popularity data
• Combo database
• Rate limit: Recommend 1 request/second
• Cached data (may not be real-time)

Project Structure

mtg-mcp/
├── main.go                  # Core MCP server, tool/resource registration
├── logger.go                # Structured logging configuration (zerolog)
├── http.go                  # HTTP utilities for API calls
├── resources.go             # MCP resource handlers (rules, banned list)
├── archidekt.go             # Archidekt API integration
├── edhrec.go                # EDHREC API integration
├── moxfield.go              # Moxfield API integration
├── *_handlers.go            # MCP tool handlers per source
│   ├── scryfall_handlers.go  # Scryfall tools (search, details, price, …)
│   ├── archidekt_handlers.go # Archidekt tools
│   ├── edhrec_handlers.go    # EDHREC tools
│   └── moxfield_handlers.go  # Moxfield tools
├── *_test.go                # Unit test files (with httptest mocks)
│   ├── archidekt_test.go    # Tests for Archidekt functionality
│   ├── edhrec_test.go       # Tests for EDHREC functionality
│   ├── moxfield_test.go     # Tests for Moxfield functionality
│   ├── http_test.go         # Tests for HTTP utilities
│   ├── logger_test.go       # Tests for logger
│   ├── server_test.go       # Tests for server construction & registration
│   ├── resources_test.go    # Tests for MCP resource handlers
│   ├── scryfall_handlers_test.go          # Tests for decklist parsing helpers
│   ├── scryfall_handlers_internal_test.go # Tests for Scryfall tool handlers
│   ├── handlers_success_test.go           # Deck-handler success-path tests
│   └── handlers_error_test.go             # Handler request-validation tests
├── *_e2e_test.go            # E2E test files (real API calls)
│   ├── archidekt_e2e_test.go # E2E tests for Archidekt API
│   ├── edhrec_e2e_test.go    # E2E tests for EDHREC API
│   ├── moxfield_e2e_test.go  # E2E tests for Moxfield API
│   └── scryfall_e2e_test.go  # E2E tests for Scryfall API
├── .github/                 # GitHub Actions workflows
│   └── workflows/
│       ├── ci.yaml          # CI pipeline (unit tests + linting)
│       ├── e2e.yaml         # Manual E2E tests + coverage workflow
│       ├── cd.yaml          # Continuous deployment
│       └── lint.yaml        # Code quality checks
├── go.mod                   # Go module dependencies
├── go.sum                   # Dependency checksums
├── mtg-mcp                  # Compiled MCP server binary
├── mtg-commander-server.log # Server log file (JSON)
└── README.md                # This file

Development

Quick Start with Makefile

The project includes a Makefile with common development tasks (compatible with macOS and Linux):

# View all available commands
make help

# Run all checks (format, lint, unit tests)
make check

# Build the binary
make build

# Run unit tests (fast)
make test-unit

# Run all tests including E2E
make test

# Run tests with coverage report
make test-coverage

# Format and lint code
make fmt lint

# Run CI pipeline locally
make ci

Common Makefile Commands:

| Command | Description | |------------------------------|----------------------------------------------------| | make help | Show all available commands | | make build | Build the binary | | make test-unit | Run unit tests only (fast, skips E2E) | | make test-e2e | Run E2E tests only | | make test | Run all tests (unit + E2E) | | make test-coverage | Generate HTML coverage report | | make test-coverage-cli | Show coverage in terminal | | make update-coverage-badge | Update coverage badge in README with proper colors | | make test-race | Run tests with race detector | | make bench | Run benchmarks | | make fmt | Format Go code | | make lint | Run all linters | | make check | Run fmt + lint + test-unit | | make ci | Run full CI pipeline locally | | make clean | Clean build artifacts | | make deps | Download dependencies | | make tidy | Tidy go.mod |

Running Tests

The project includes comprehensive unit tests with good coverage:

# Run all tests (unit tests only, skips E2E)
go test -short -v ./...

# Run tests with coverage
go test -short -v -race -coverprofile=coverage.out -covermode=atomic ./...

# View coverage report
go tool cover -html=coverage.out

End-to-End (E2E) Tests

E2E tests validate the integration with real external APIs (Scryfall, EDHREC, Moxfield) and are not run automatically in CI. They test:

• Real API connectivity and response formats
• Data structure validation with actual API responses
• Card name sanitization with real EDHREC endpoints
• Moxfield deck fetching and search
• Scryfall card queries and pricing

Running E2E Tests Locally:

# Run all tests including E2E (no -short flag)
go test -v ./...

# Run only E2E tests
go test -v -run E2E ./...

# Run with timeout for slower APIs
go test -v -timeout 5m ./...

Running E2E Tests via GitHub Actions:

E2E tests can be triggered manually through the GitHub Actions workflow:

1. Go to the "Actions" tab in the repository
2. Select "E2E Tests & Coverage" wo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nathanmartins
• Source: nathanmartins/mtg-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.