MTG MCP Server

Install

Config snippet generator goes here (5 client tabs)

README

<!-- mcp-name: io.github.j4th/mtg-mcp-server -->
# mtg-mcp-server

[![CI](https://github.com/j4th/mtg-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/j4th/mtg-mcp-server/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mtg-mcp-server)](https://pypi.org/project/mtg-mcp-server/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)](https://github.com/j4th/mtg-mcp-server)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![codecov](https://codecov.io/gh/j4th/mtg-mcp-server/graph/badge.svg)](https://codecov.io/gh/j4th/mtg-mcp-server)
[![CodeQL](https://github.com/j4th/mtg-mcp-server/workflows/CodeQL/badge.svg)](https://github.com/j4th/mtg-mcp-server/actions/workflows/codeql.yml)
[![Smithery](https://smithery.ai/badge/@j4th/mtg-mcp-server)](https://smithery.ai/server/@j4th/mtg-mcp-server)
[![Dependabot](https://img.shields.io/badge/dependabot-enabled-blue?logo=dependabot)](https://github.com/j4th/mtg-mcp-server/security/dependabot)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

A Magic: The Gathering MCP server for AI assistants. Search cards, analyze draft formats, explore Commander combos, evaluate deck upgrades — all from Claude Code, Claude Desktop, or any MCP client.

> **Built on data from [Scryfall](https://scryfall.com), [Commander Spellbook](https://commanderspellbook.com), [17Lands](https://www.17lands.com), [EDHREC](https://edhrec.com), and [MTGJSON](https://mtgjson.com).** See [Data Sources & Attribution](#data-sources--attribution) for details and usage terms.

## What It Does

**Card Data** (via Scryfall) — Search the full MTG card database, check prices, look up rulings, verify format legality.

**Combo Discovery** (via Commander Spellbook) — Find combos for any commander or card, estimate deck bracket/power level.

**Draft Analytics** (via 17Lands) — Card win rates by set and archetype, format speed analysis, draft pick recommendations.

**Commander Metagame** (via EDHREC) — Top cards by commander, synergy scores, inclusion rates, average decklists.

**Composed Workflows** — Higher-level tools that cross-reference multiple sources: commander overviews, upgrade evaluations, sealed pool analysis, deck audits.

## Install

Requires Python 3.12+. No API keys needed — all data sources are public.

```bash
# Run directly with uvx (no install needed)
uvx mtg-mcp-server

# Or install globally
uv tool install mtg-mcp-server

# Or install in a project
uv add mtg-mcp-server
```

## Connect to Claude Code

```bash
claude mcp add mtg -- uvx mtg-mcp-server
```

Or add to your MCP config (`.mcp.json` or `~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "mtg": {
      "command": "uvx",
      "args": ["mtg-mcp-server"]
    }
  }
}
```

Then in Claude Code:

```
> Search for Sultai creatures with CMC 3 or less that are legal in Commander
> What combos does Muldrotha enable?
> Show me draft ratings for the top BG commons in Lorwyn Eclipsed
> Evaluate adding Spore Frog to my Muldrotha deck, cutting Eternal Skylord
```

## Connect to Claude Desktop

Add to your Claude Desktop config:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mtg": {
      "command": "uvx",
      "args": ["mtg-mcp-server"]
    }
  }
}
```

## Configuration

All settings use `MTG_MCP_` environment variables with sensible defaults. No configuration required to get started.

```bash
# Disable optional backends
MTG_MCP_ENABLE_EDHREC=false    # EDHREC scrapes undocumented endpoints
MTG_MCP_ENABLE_17LANDS=false   # 17Lands rate-limits aggressively
MTG_MCP_ENABLE_MTGJSON=false   # MTGJSON downloads ~100MB bulk file on first use

# Pass env vars to uvx
uvx --env MTG_MCP_ENABLE_EDHREC=false mtg-mcp-server
```

See `.env.example` for all available options.

## Local Install (from source)

If you want to run from a local checkout instead of PyPI:

```bash
git clone https://github.com/j4th/mtg-mcp-server.git
cd mtg-mcp-server
mise install && mise run setup

# Run the server directly
uv run mtg-mcp-server

# Or use uvx with a local path
uvx --from /path/to/mtg-mcp-server mtg-mcp-server
```

Claude Code config for a local install:

```json
{
  "mcpServers": {
    "mtg": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mtg-mcp-server", "mtg-mcp-server"]
    }
  }
}
```

## Development

```bash
git clone https://github.com/j4th/mtg-mcp-server.git
cd mtg-mcp-server
mise install          # Installs Python, uv, ruff, ty
mise run setup        # Creates venv, installs dependencies

mise run check        # Full quality gate: lint + format + typecheck + test
mi