mtg-mcp-server

KO | EN

gitlite — search

#llm #golang #android #machine-learning #rust #deep-learning #docker #macos #awesome #cli #security #pytorch #mcp #open-source

(★ 16)

Unified MCP server composing Scryfall, Commander Spellbook, 17Lands, EDHREC, Moxfield, Spicerack, and MTGGoldfish into one interface for AI assistants. 69 tools for Commander analytics, draft evaluation, competitive metagame, sideboard strategy, and more.

mtg-mcp-server 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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)](https://raw.githubusercontent.com/j4th/mtg-mcp-server/main/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)

69 tools, 19 prompts, and 21 resources that give AI assistants deep access to Magic: The Gathering -- card data, combos, draft analytics, Commander metagame, competitive constructed, sideboard strategy, deck building, rules engine, and more. Works with 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), [Moxfield](https://www.moxfield.com), [Spicerack](https://spicerack.gg), and [MTGGoldfish](https://www.mtggoldfish.com). See [Data Sources & Attribution](#data-sources--attribution) for details and usage terms.

## Table of Contents

- [What You Can Do](#what-you-can-do) — example prompts and real tool output
- [Install](#install) — hosted, Claude Code, Claude Desktop, PyPI, development
- [Configuration](#configuration) — environment variables and feature flags
- [Tools](#tools) — all 69 tools across 13 domains
- [Architecture](#architecture) — FastMCP 3.x mount system
- [Stack](#stack) — Python 3.12+, FastMCP, httpx, Pydantic
- [Development](#development) — mise commands for testing, linting, typechecking
- [Documentation](#documentation) — cookbook, architecture, tool reference, and more
- [Status](#status) — current tool/test counts
- [Data Sources & Attribution](#data-sources--attribution) — Scryfall, Spellbook, 17Lands, EDHREC, Moxfield, Spicerack, MTGGoldfish

## What You Can Do

Ask your AI assistant questions like these and it will use the MTG tools automatically:

**Commander**
- "Show me everything about Muldrotha as a commander"
- "What are the best budget upgrades for my Atraxa deck under $5?"
- "Compare Muldrotha vs Meren vs Karador as graveyard commanders"

**Draft & Limited**
- "What are the best commons in Foundations for draft?"
- "Rank these cards for my draft pack: Bitter Triumph, Monstrous Rage, Torch the Tower"
- "Build a sealed deck from this pool: [list]"

**Deck Building**
- "Validate my Modern decklist"
- "Suggest a mana base for my 3-color Commander deck"
- "Find cards that synergize with sacrifice themes in Golgari"

**Rules**
- "How do deathtouch and trample interact?"
- "Resolve this combat scenario: my 3/3 with first strike blocks their 5/5 with trample"

**Constructed**
- "What does the Modern metagame look like right now?"
- "Show me the stock Boros Energy decklist for Modern"
- "Build me a sideboard for this Pioneer deck"
- "Give me a sideboard guide for my deck against Azorius Control"

### See It in Action

> "Compare Muldrotha, Meren, and Karador as graveyard commanders"

```
                     Muldrotha            Meren               Karador
Mana Cost            {3}{B}{G}{U}         {2}{B}{G}           {5}{W}{B}{G}
Color Identity       BGU (Sultai)         BG (Golgari)        BGW (Abzan)
Stats                6/6                  3/4                  3/4
EDHREC Rank          #1,137               #1,476              #9,894
Total Decks          22,460               19,919              6,305
Combo Count          10                   1                   10

Top Staples:
  Muldrotha           Spore Frog (+53%), Sakura-Tribe Elder (+36%), Eternal Witness (+27%)
  Meren               Spore Frog (+70%), Sakura-Tribe Elder (+55%), Viscera Seer (+52%)
  Karador             Karmic Guide (+51%), Satyr Wayfinder (+49%), Sun Titan (+48%)
```

> "What are the best commons in Foundations for draft?"

```
Foundations (FDN) — PremierDraft · Median GIH WR: 54.7%

Rank  Card               Color  GIH WR   ALSA   IWD      Games
1     Bake into a Pie    B      58.4%    3.1    +5.3%    354,741
2     Burst Lightning    R      58.2%    3.3    +3.0%    338,888
3     Refute             U      58.1%    5.3    +4.3%    321,280
4     Stab               B      57.9%    3.4    +4.5%    376,569
5     Dazzling Angel     W      57.8%    3.2    +2.4%    317,648

Trap rares: Doubling Season (39.4%), Thousand-Year Storm (35.2%) ...
```

More examples with real tool output in the [Cookbook](docs/COOKBOOK.md).

## Install

No API keys needed -- all data sources are public.

### Hosted (zero setup)

The fastest way to get started. No Python install required. Works on mobile.

**Via the UI** (Claude Desktop or claude.ai): Settings → Connectors → Add custom connector → paste the URL:

```
https://mtg-mcp-server.fastmcp.app/mcp
```

**Via config file** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "mtg": {
      "type": "url",
      "url": "https://mtg-mcp-server.fastmcp.app/mcp"
    }
  }
}
```

### Claude Code

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

Or via the UI: Settings → MCP Servers → Add server → enter `uvx mtg-mcp-server` as the command.

### Claude Desktop (local)

Runs on your machine. Requires Python 3.12+.

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

### PyPI

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

# Install globally
uv tool install mtg-mcp-server

# Add to a project
uv add mtg-mcp-server
```

### Development

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

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

Claude Code config for local development:

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

## Configuration

All settings use `MTG_MCP_` environment variables. Everything works out of the box with sensible defaults.

```bash
# Feature flags for optional backends
MTG_MCP_ENABLE_EDHREC=false       # EDHREC (scrapes undocumented endpoints)
MTG_MCP_ENABLE_17LANDS=false      # 17Lands (rate-limits aggressively)
MTG_MCP_ENABLE_BULK_DATA=false    # Scryfall bulk data (~30MB download on first use)
MTG_MCP_ENABLE_RULES=false        # Comprehensive Rules engine

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

See `.env.example` for all available options including base URLs, rate limits, and cache settings.

## Tools

69 tools across 13 domains. See [docs/TOOL_DESIGN.md](docs/TOOL_DESIGN.md) for full input/output details.

### Card Data (`scryfall_*`)

| Tool | Description |
|------|-------------|
| `search_cards` | Search using full Scryfall syntax (`f:commander id:sultai t:creature`) |
| `card_details` | Full card data by exact or fuzzy name |
| `card_price` | Current USD, EUR, and foil prices |
| `card_rulings` | Official rulings and clarifications |
| `set_info` | Set metadata by code |
| `whats_new` | Recently released or previewed cards |

### Bulk Data (`bulk_*`)

| Tool | Description |
|------|-------------|
| `card_lookup` | Rate-limit-free card lookup by exact name |
| `card_search` | Search by name, type, or oracle text |
| `format_legality` | Check if a card is legal in a format |
| `format_search` | Search for cards legal in a specific format |
| `format_staples` | Top-played cards in a format by EDHREC rank |
| `ban_list` | Banned and restricted cards for a format |
| `card_in_formats` | Card legality across all formats |
| `random_card` | Random card, optionally filtered by format or type |
| `similar_cards` | Find cards similar by type, keywords, or mana cost |

### Combos (`spellbook_*`)

| Tool | Description |
|------|-------------|
| `find_combos` | Search for combos by card name and color identity |
| `combo_details` | Step-by-step combo instructions by ID |
| `find_decklist_combos` | Find combos present in a decklist |
| `estimate_bracket` | Estimate Commander bracket for a decklist |

### Draft Analytics (`draft_*`)

| Tool | Description |
|------|-------------|
| `card_ratings` | Win rates and draft data for cards in a set (17Lands) |
| `archetype_stats` | Win rates by color pair for a set |

### Commander Metagame (`edhrec_*`)

| Tool | Description |
|------|-------------|
| `commander_staples` | Most-played cards for a commander with synergy scores |
| `card_synergy` | Synergy data for a card with a specific commander |

### Decklists (`moxfield_*`)

| Tool | Description |
|------|-------------|
| `decklist` | Fetch a full decklist by deck ID or URL |
| `deck_info` | Deck metadata (name, format, author, dates) |
| `search_decks` | Search public decks by format, keyword, or sort order |
| `user_decks` | List a user's public decks |

### Tournament Data (`spicerack_*`)

| Tool | Description |
|------|-------------|
| `recent_tournaments` | Recent tournaments for a competitive format |
| `tournament_results` | Full standings for a specific tournament |
| `format_decklists` | Top-finishing decklists across recent tournaments |

### Metagame (`goldfish_*`)

| Tool | Description |
|------|-------------|
| `metagame` | Current metagame breakdown for a competitive format |
| `archetype_list` | Sample decklist for an archetype |
| `format_staples` | Most-played cards in a format with deck inclusion % |
| `deck_price` | Estimated paper price for an archetype deck |

### Commander Workflows

| Tool | Description |
|------|-------------|
| `commander_overview` | Full commander profile from all sources |
| `evaluate_upgrade` | Assess whether a card is worth adding to a deck |
| `card_comparison` | Compare 2-5 cards side-by-side for a commander |
| `budget_upgrade` | Budget-constrained upgrade suggestions ranked by synergy/$ |
| `commander_comparison` | Compare 2-5 commanders head-to-head |
| `color_identity_staples` | Top-played cards across all commanders in a color identity |

### Deck Building

| Tool | Description |
|------|-------------|
| `theme_search` | Find cards matching a mechanical or tribal theme |
| `build_around` | Detect synergies from key cards and find complements |
| `complete_deck` | Gap analysis and suggestions for a partial decklist |
| `tribal_staples` | Best cards for a creature type in a color identity |
| `precon_upgrade` | Analyze a precon and suggest swap pairs |
| `suggest_cuts` | Identify the weakest cards to cut from a decklist |
| `deck_analysis` | Full decklist health check (curve, colors, combos, budget) |
| `deck_validate` | Validate a decklist against format construction rules |
| `suggest_mana_base` | Suggest lands based on color pip distribution |
| `price_comparison` | Compare prices across multiple cards |

### Draft Workflows

| Tool | Description |
|------|-------------|
| `draft_pack_pick` | Rank cards in a draft pack using 17Lands data |
| `set_overview` | Top commons/uncommons and trap rares for a format |
| `sealed_pool_build` | Suggest the best 40-card builds from a sealed pool |
| `draft_signal_read` | Detect open colors from draft picks |
| `draft_log_review` | Pick-by-pick review of a completed draft with grade |

### Constructed Workflows

| Tool | Description |
|------|-------------|
| `rotation_check` | Standard rotation status and rotating cards |
| `metagame_snapshot` | Tiered metagame breakdown with prices |
| `archetype_decklist` | Stock decklist for a competitive archetype |
| `archetype_comparison` | Compare 2-4 archetypes side-by-side |
| `format_entry_guide` | Beginner guide for entering a competitive format |
| `suggest_sideboard` | 15-card sideboard suggestions for a deck |
| `sideboard_guide` | In/out plan for a specific matchup |
| `sideboard_matrix` | Sideboard matrix across common matchups |

### Rules Engine

| Tool | Description |
|------|-------------|
| `rules_lookup` | Look up rules by number or keyword |
| `keyword_explain` | Explain a keyword with rules and example cards |
| `rules_interaction` | How two mechanics interact with rule citations |
| `rules_scenario` | Rules framework for a game scenario |
| `combat_calculator` | Step-by-step combat phases with keyword interactions |

## Architecture

Built on **FastMCP 3.x**. Each data source is an independent sub-server mounted into a single orchestrator:

```
MTG (orchestrator)
├── scryfall (namespace: scryfall_)     -> Scryfall REST API
├── spellbook (namespace: spellbook_)   -> Commander Spellbook API
├── draft (namespace: draft_)           -> 17Lands data
├── edhrec (namespace: edhrec_)         -> EDHREC (scraped, feature-flagged)
├── bulk (namespace: bulk_)             -> Scryfall Oracle Cards bulk data
├── moxfield (namespace: moxfield_)     -> Moxfield (reverse-engineered, feature-flagged)
├── spicerack (namespace: spicerack_)   -> Spicerack tournament API
├── goldfish (namespace: goldfish_)     -> MTGGoldfish (scraped, feature-flagged)
└── workflows (no namespace)            -> 36 tools (31 composed + 5 rules)
```

Services are pure async API clients. Providers register MCP tools. Workflows compose across services with partial failure tolerance. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full picture.

## Stack

| | |
|---|---|
| Runtime | Python 3.12+, uv |
| MCP | FastMCP 3.2.x |
| HTTP | httpx (async) |
| Validation | Pydantic v2 |
| Logging | structlog |
| Tooling | mise, ruff, ty (Astral) |
| Testing | pytest, respx, pytest-asyncio |
| HTML parsing | selectolax |

## 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 + typecheck + tests
mise run check:quick  # Fast gate: lint + typecheck + affected tests only
mise run test         # All tests with coverage
mise run test:quick   # Only tests affected by recent changes
mise run lint         # ruff check + format check
mise run typecheck    # ty check
mise run dev          # MCP Inspector for interactive testing
mise run fix          # Auto-fix lint and format issues
```

## Documentation

| Doc | What it covers |
|-----|----------------|
| [COOKBOOK.md](docs/COOKBOOK.md) | Usage recipes -- Commander, draft, deck building, rules workflows |
| [TOOL_DESIGN.md](docs/TOOL_DESIGN.md) | Full reference for all 69 tools, 19 prompts, 21 resources |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Technical architecture, FastMCP patterns, design decisions |
| [SERVICE_CONTRACTS.md](docs/SERVICE_CONTRACTS.md) | API endpoints, rate limits, response shapes per backend |
| [DATA_SOURCES.md](docs/DATA_SOURCES.md) | All data sources with auth, stability, and access patterns |
| [CACHING_DESIGN.md](docs/CACHING_DESIGN.md) | TTL cache strategy and Scryfall bulk data design |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, TDD workflow, code style, PR process |
| [CHANGELOG.md](CHANGELOG.md) | Version history in Keep a Changelog format |

## Status

69 tools, 19 prompts, 21 resource templates. 1340 tests at 88% coverage.

| Phase | What | Status |
|-------|------|--------|
| 0 | Project scaffold | Done |
| 1 | Scryfall backend (4 tools) | Done |
| 2 | Spellbook + 17Lands + EDHREC backends (9 tools) | Done |
| 3 | Workflow tools -- commander, draft, deck (4 tools) | Done |
| 4 | TTL caching + Scryfall bulk data provider (2 tools) | Done |
| 5 | Analysis & comparison workflows, prompts, resources (4 tools) | Done |
| Branch A | Structured output, rules engine, validation tools (17 tools) | Done |
| Branch B | Format workflows -- deck building, commander depth, limited, constructed (11 tools) | Done |
| Moxfield | Moxfield decklist provider (4 tools) | Done |
| Spicerack | Tournament results provider (3 tools) | Done |
| MTGGoldfish | Metagame data provider (4 tools) | Done |
| v2.3.0 | Metagame workflows, sideboard tools, Moxfield search (9 tools) | Done |

## Data Sources & Attribution

This project composes data from multiple third-party services:

- **[Scryfall](https://scryfall.com)** -- Card database, prices, rulings, search, bulk data ([API guidelines](https://scryfall.com/docs/api))
- **[Commander Spellbook](https://commanderspellbook.com)** -- Combo search, bracket estimation ([MIT license](https://github.com/SpaceCowMedia/commander-spellbook-backend))
- **[17Lands](https://www.17lands.com)** -- Draft card ratings, archetype win rates ([usage guidelines](https://www.17lands.com/usage_guidelines))
- **[EDHREC](https://edhrec.com)** -- Commander staples, synergy scores (undocumented endpoints, behind feature flag)
- **[Moxfield](https://www.moxfield.com)** -- Public decklists and deck search (reverse-engineered API, behind feature flag)
- **[Spicerack](https://spicerack.gg)** -- Tournament results and standings ([documented API](https://docs.spicerack.gg))
- **[MTGGoldfish](https://www.mtggoldfish.com)** -- Competitive metagame data, archetypes, format staples (HTML scraping, behind feature flag)

See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for full license texts and usage terms.

## Disclaimer

mtg-mcp-server is unofficial Fan Content permitted under the [Fan Content Policy](https://company.wizards.com/en/legal/fancontentpolicy). Not approved/endorsed by Wizards. Portions of the materials used are property of Wizards of the Coast. &copy; Wizards of the Coast LLC.

## License

MIT -- see [LICENSE](LICENSE)

mtg-mcp-server

mtg-mcp-server 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

mtg-mcp-server

mtg-mcp-server 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README