mtg-mcp

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

<p align="center">
  <img src="assets/logo.svg" alt="mtg-mcp logo" width="220" />
</p>

[![CI](https://github.com/nccurry/mtg-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nccurry/mtg-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/nccurry/mtg-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/nccurry/mtg-mcp)
[![NuGet](https://img.shields.io/nuget/v/Nccurry.MtgMcp?label=NuGet)](https://www.nuget.org/packages/Nccurry.MtgMcp)
[![NuGet downloads](https://img.shields.io/nuget/dt/Nccurry.MtgMcp?label=downloads)](https://www.nuget.org/packages/Nccurry.MtgMcp)
[![.NET](https://img.shields.io/badge/.NET-11.0-512BD4)](https://dotnet.microsoft.com/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.nccurry%2Fmtg--mcp-0f766e)](https://registry.modelcontextprotocol.io/?q=io.github.nccurry%2Fmtg-mcp)
[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)

`mtg-mcp` is an unofficial MCP server for Magic: The Gathering deckbuilding. It
connects MCP clients to Scryfall card data, local deck workspaces, optional
Moxfield imports, Archidekt writeback, Playgroup.gg playgroup data, Commander
Spellbook combos, and API-backed deckbuilding evidence.

It is not affiliated with Hasbro, Wizards of the Coast, Magic: The Gathering,
Scryfall, Moxfield, Archidekt, Playgroup.gg, or Commander Spellbook.

## Install

### NuGet .NET Tool

The easiest manual install is the published NuGet tool package:

```bash
dotnet tool install --global Nccurry.MtgMcp
mtg-mcp --version
mtg-mcp --smoke
```

To upgrade an existing install:

```bash
dotnet tool update --global Nccurry.MtgMcp
```

PowerShell note: when invoking the executable by a quoted full path, prefix it
with the call operator:

```powershell
& "C:\Users\you\.dotnet\tools\mtg-mcp.exe" --version
```

### MCP Registry

Registry-aware MCP clients can discover the server by its registry name:

```text
io.github.nccurry/mtg-mcp
```

The registry entry points to the NuGet package `Nccurry.MtgMcp` and uses stdio
transport. You can also inspect it in the
[official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.nccurry%2Fmtg-mcp).

### GitHub Release Archive

Release archives are attached to
[GitHub Releases](https://github.com/nccurry/mtg-mcp/releases/latest) for the
published desktop runtimes:

- `win-x64`: download `mtg-mcp-<version>-win-x64.zip`.
- `linux-x64`: download `mtg-mcp-<version>-linux-x64.tar.gz`.
- `osx-arm64`: download `mtg-mcp-<version>-osx-arm64.tar.gz`.

Extract the archive and configure your MCP client to run the extracted
`mtg-mcp` executable.

### From Source

For local development or testing an unreleased branch:

```bash
git clone https://github.com/nccurry/mtg-mcp.git
cd mtg-mcp
./bootstrap.sh
task install:local
```

On Windows:

```powershell
git clone https://github.com/nccurry/mtg-mcp.git
cd mtg-mcp
.\bootstrap.ps1
task install:local
```

`task install:local` packs the current checkout, publishes a self-contained
binary for the current machine, and updates the configured local MCP command
path when possible.

### MCP Client Configuration

Configure your MCP client to run the `mtg-mcp` stdio command. Scryfall lookup
and local deck analysis work without account credentials.

Codex example:

```bash
codex mcp add mtg-mcp \
  --env MTGMCP__OPERATION_MODE=plan \
  -- mtg-mcp
```

JSON MCP client example:

```json
{
  "mcpServers": {
    "mtg-mcp": {
      "command": "mtg-mcp",
      "env": {
        "MTGMCP__OPERATION_MODE": "plan"
      }
    }
  }
}
```

Set `MTGMCP__OPERATION_MODE` explicitly:

- `read-only`: lookup and analysis only.
- `plan`: lookup, analysis, metadata refresh, and saved edit plans.
- `apply`: deck edits, checkpoints, and Archidekt writeback. Writeback still
  requires opening the Archidekt workspace with writeback enabled.

## Features

| Area | What the MCP exposes |
| --- | --- |
| Card data | Scryfall search with optional format legality filtering, fuzzy card lookup, prints, rulings, and Scryfall query syntax guidance. |
| Workspaces | Create, import, parse, export, open, validate, summarize, migrate, and update local or Archidekt-backed decks. |
| Deck editing | Add, remove, move, categorize, annotate, and set quantities; create, preview, list, apply, or delete persisted edit plans. |
| Moxfield | Import public or unlisted decks as generic local workspaces while preserving boards, tags, and print metadata when available. |
| Archidekt | Create decks, open decks, list visible decks, write back when enabled, copy local workspaces into Archidekt, and manage deck checkpoints. |
| Playgroup.gg | Check auth, get playgroups and decks, list playgroup users/decks, list user decks, rank decks by power, Elo, win rate, competitive rating, games played, or average win turn, and score candidate cards against local-meta pressure. |
| Analysis | Mana base, curve, colors, categories, cost, legality, draw odds, consistency, best practices, Commander bracket, card facets, and explicit facet predicates. |
| Simulation | Goldfish runs, projected board states, win-turn estimates, deterministic performance analysis, plan comparisons, and Archidekt reference comparisons. |
| Recommendations | New-card swap evidence, Commander aggregate cards/tags, win-condition evidence, caller-supplied Scryfall queries, lesser-known cards, commander trends, exemplar decks, raw source evidence, and Reddit discussion evidence. |
| Combos | Catalog-backed combo search/details, deck combo analysis, route labels, terminal/needs-payoff flags, near-misses, and clearly separated local heuristics. |
| Deck intent | Optional human-readable deck goals, budgets, local meta, role targets, simulation profiles, win routes, preferences, avoided cards, and protected cards. |

Most users can ask naturally instead of naming tools:

```text
Open this Archidekt deck locally, analyze the mana base, and suggest fixes under $10.
```

```text
Import this Moxfield deck, dry-run copying it to a new private Archidekt deck, and preserve its tags.
```

Moxfield role tags import as secondary workspace categories. When copied to
Archidekt, those tag categories are marked as not included in deck totals so
Mainboard, Commander, and other board categories still control legality and
deck size. Existing Archidekt copies can be repaired or refreshed with
`archidekt_copy_workspace` using `replaceExistingDestination=true`.

```text
Find budget replacements for cards over $20 and preview the plan before changing anything.
```

```text
List decks from this Playgroup URL and rank them by win rate.
```

```text
Find new cards for this deck from the last year and explain the source evidence.
```

```text
Goldfish this deck through turn 6 and compare the previewed plan against it.
```

## Configuration

`mtg-mcp.json` is the only JSON config file the server reads. Environment
variables use the `MTGMCP__...` names below; the equivalent JSON path is under
`MtgMcp`. For example, `MTGMCP__PLAYGROUP__CREDENTIALS_FILE` maps to
`MtgMcp.Playgroup.CredentialsFile`.

Minimal `mtg-mcp.json`:

```json
{
  "MtgMcp": {
    "OperationMode": "plan",
    "DataDir": "C:/Users/you/AppData/Local/mtg-mcp"
  }
}
```

Common credential config:

```json
{
  "MtgMcp": {
    "Archidekt": {
      "CredentialsFile": "C:/Users/you/.mtg-mcp/archidekt.json"
    },
    "Playgroup": {
      "CredentialsFile": "C:/Users/you/.mtg-mcp/playgroup.json"
    },
    "Reddit": {
      "CredentialsFile": "C:/Users/you/.mtg-mcp/reddit.json"
    }
  }
}
```

`archidekt.json`:

```json
{
  "username": "you-or-you@example.com",
  "password": "..."
}
```

Archidekt does not expose a public self-service page for generating refresh
tokens, so Archidekt credentials are configured as username and password only.
The `username` value can be your Archidekt username or account email address.

`playgroup.json`:

```json
{
  "apiKey": "..."
}
```

`reddit.json`:

```json
{
  "clientId": "...",
  "clientSecret": "...",
  "refreshToken": "...",
  "userAgent": "mtg-mcp/1.0 by your-reddit-username",
  "scope": "read"
}
```

Reddit uses OAuth bearer tokens through `https://oauth.reddit.com`, not a
long-lived API key. A refresh token plus app client id is the preferred local
setup; a temporary `accessToken` or `bearerToken` can be stored for short-lived
testing.

You can also create an Archidekt credentials file with:

```bash
mtg-mcp auth archidekt \
  --credentials-file "$HOME/.mtg-mcp/archidekt.json" \
  --username "you-or-you@example.com" \
  --password "..."
```

PowerShell equivalent:

```powershell
mtg-mcp auth archidekt `
  --credentials-file "$env:USERPROFILE\.mtg-mcp\archidekt.json" `
  --username "you-or-you@example.com" `
  --password "..."
```

You can create a Playgroup credentials file the same way:

```bash
mtg-mcp auth playgroup \
  --credentials-file "$HOME/.mtg-mcp/playgroup.json" \
  --api-key "..."
```

PowerShell equivalent:

```powershell
mtg-mcp auth playgroup `
  --credentials-file "$env:USERPROFILE\.mtg-mcp\playgroup.json" `
  --api-key "..."
```

Create a Reddit OAuth credentials file with:

```bash
mtg-mcp auth reddit \
  --credentials-file "$HOME/.mtg-mcp/reddit.json" \
  --client-id "..." \
  --client-secret "..." \
  --refresh-token "..." \
  --user-agent "mtg-mcp/1.0 by your-reddit-username"
```

PowerShell equivalent:

```powershell
mtg-mcp auth reddit `
  --credentials-file "$env:USERPROFILE\.mtg-mcp\reddit.json" `
  --client-id "..." `
  --client-secret "..." `
  --refresh-token "..." `
  --user-agent "mtg-mcp/1.0 by your-reddit-username"
```

Supported environment settings. In rows with slashes, repeat the full prefix for
each abbreviated suffix.

| Setting | Use |
| --- | --- |
| `MTGMCP__OPERATION_MODE` | `read-only`, `plan`, or `apply`. Set explicitly; the app default is `apply`. |
| `MTGMCP__DATA_DIR` | Local decks, plans, workspaces, and source-fact cache. |
| `MTGMCP__INT