mtg-mcp

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

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

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:

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

To upgrade an existing install:

dotnet tool update --global Nccurry.MtgMcp

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

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

MCP Registry

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

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.

GitHub Release Archive

Release archives are attached to GitHub Releases 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:

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

On Windows:

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:

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

JSON MCP client example:

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

Most users can ask naturally instead of naming tools:

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

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.

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

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

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

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:

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

Common credential config:

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

{
  "username": "[email protected]",
  "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:

{
  "apiKey": "..."
}

reddit.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:

mtg-mcp auth archidekt \
  --credentials-file "$HOME/.mtg-mcp/archidekt.json" \
  --username "[email protected]" \
  --password "..."

PowerShell equivalent:

mtg-mcp auth archidekt `
  --credentials-file "$env:USERPROFILE\.mtg-mcp\archidekt.json" `
  --username "[email protected]" `
  --password "..."

You can create a Playgroup credentials file the same way:

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

PowerShell equivalent:

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

Create a Reddit OAuth credentials file with:

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:

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.

Recommendation sources

Recommendation source providers give deckbuilding tools source-backed evidence beyond the local decklist. Use source_list or mtg://sources/status to report the current source status:

• available: the provider can be queried.
• missing-config: the provider is implemented, but needs a configured key.
• disabled: the provider is implemented, but disabled by configuration.
• failed: the provider failed during a lookup; other sources still run.

TopDeck.gg and Spicerack are API-backed decklist recommendation sources. They are enabled by default, but they do not make network calls until an API key is configured.

$env:MTGMCP__INTELLIGENCE__SOURCES__TOPDECK__API_KEY = "..."
$env:MTGMCP__INTELLIGENCE__SOURCES__SPICERACK__API_KEY = "..."

Equivalent mtg-mcp.json:

{
  "MtgMcp": {
    "Intelligence": {
      "Sources": {
        "TopDeck": {
          "ApiKey": "..."
        },
        "Spicerack": {
          "ApiKey": "..."
        }
      }
    }
  }
}

Set Enabled to false for either source to exclude it:

{
  "MtgMcp": {
    "Intelligence": {
      "Sources": {
        "TopDeck": {
          "Enabled": false
        }
      }
    }
  }
}

TopDeck.gg uses the documented tournaments v2 API for tournament standings and decklists. Get a key from TopDeck.gg and keep visible attribution when using its data in user-facing output. Spicerack uses the documented public decklist database API for recent tournament results and decklist text.

EDHREC is enabled by default as an unofficial source for broad Commander aggregate inclusion and synergy evidence. It uses structured JSON pages only, never HTML scraping or browser automation. Set AllowUnofficialApi to false to exclude it:

$env:MTGMCP__INTELLIGENCE__SOURCES__EDHREC__ALLOW_UNOFFICIAL_API = "false"

Equivalent mtg-mcp.json:

{
  "MtgMcp": {
    "Intelligence": {
      "Sources": {
        "Edhrec": {
          "AllowUnofficialApi": false
        }
      }
    }
  }
}

EDHREC evidence is cached, attribution-sensitive, and not backed by a stable public API contract. Treat it as popularity and synergy context, not tournament performance or source decklist evidence. Commander theme filters are used only when a source exposes deterministic theme slugs; other sources return an unsupported-theme note instead of silently falling back to broader rows.

Reddit discussion evidence is also enabled by default for bounded searches over Commander-focused subreddits. Configure Reddit OAuth credentials with mtg-mcp auth reddit or MTGMCP__REDDIT__... settings to use bearer requests against https://oauth.reddit.com. Public JSON fallback remains available only when OAuth credentials are absent and AllowUnofficialApi permits it; treat that fallback as unreliable and less preferred. EDHTop16 remains opt-in because it uses an unofficial cEDH-focused endpoint rather than broad casual Commander data.

These tools consume recommendation sources or source-backed catalog evidence:

• commander_get_aggregate_cards: returns commander card rows grouped by

source. It does not merge unlike populations when source is omitted.

• commander_get_tags: returns source-backed commander tags and themes.
• commander_get_win_condition_evidence: bundles aggregate cards, tags,

commander-containing combos, route classifications, and payoff candidates as structured evidence only.

• deck_review_new_card_swaps: returns new-card swap evidence plus

deterministic cut evidence, not automatic edits.

• deck_find_exemplar_decks: returns high-signal source decks.
• deck_analyze_commander_trends: ranks card candidates from enabled sources.
• deck_find_lesser_known_cards: finds lower-known candidates with source evidence.
• source_explain_card_signal: explains one card's source signal in a deck context.
• source_search_evidence: inspects one source by key, such as topdeck,

spicerack, or edhrec, without making deckbuilding choices.

• source_search_reddit_discussions: returns bounded raw discussion rows and

card mentions; Reddit is never treated as prevalence evidence.

TopDeck and Spicerack evidence is tournament and event decklist evidence. It is not broad casual Commander inclusion data. Use bypassCache=true on source-backed recommendation tools to bypass fresh source-fact cache entries for one call.

Use these resources inside an MCP client to verify setup without exposing secrets:

• mtg://config/effective
• mtg://server/info
• mtg://providers/archidekt/auth-status
• mtg://providers/playgroup/auth-status
• mtg://sources/status

MCP Surface

Workflow-first tools:

• Start or open workspaces with workspace_start, workspace_list, and

workspace_open; parse, export, and validate with workspace_parse_decklist, workspace_export, workspace_validate, workspace_validate_legality, workspace_checkpoint_create, workspace_refresh_from_source, and workspace_diff_last_import.

• Search cards with card_search, card_get, card_get_prints, and

card_get_rulings.

• Inspect decks with deck_summarize, deck_analyze_structure,

deck_analyze_mana, deck_analyze_consistency, and deck_analyze_performance; use deck_analyze_land_drop_odds for the turn-by-turn land-drop question, or deck_re_evaluate for a compact updated deck health snapshot. Use deck_compare_workspaces_analysis when you need validation, legality, mana, consistency, cost, role, risk, and optional performance deltas against an explicit or last-import baseline.

• Inspect local category contents with deck_list_cards_by_category, or use

deck_list_cards_by_zone for active, sideboard, maybeboard, excluded, and all-card views with optional duplicate collapsing; a newly created or implicit Sideboard category is excluded from deck and price accounting unless imported data explicitly says otherwise.

• Compare no-interaction goldfish outputs with deck_compare_goldfish. Its

default optimistic-goldfish-model preserves the existing heuristic output; opt into rules-backed-goldfish-race-v1 for a conservative template life-total race that reports explicit assumptions and unsupported-text warnings.

• Inspect combos and win routes with deck_analyze_combos,

combo_search_by_card, combo_get_details, card_classify_win_routes, and wincon_find_payoffs.

• Research changes with deck_query_cards, deck_review_new_card_swaps,

commander_get_aggregate_cards, commander_get_win_condition_evidence, source tools, and Playgroup tools.

• Preview edits with deck_plan_create, deck_plan_preview, and

deck_plan_compare_performance; apply only with deck_plan_apply.

• Apply package-style local edits with deck_add_cards_bulk,

deck_update_card_categories_bulk, and deck_move_cards_bulk when many candidates or category changes should validate together and persist once.

• Use provider tools such as archidekt_copy_workspace,

archidekt_checkpoint_create, and playgroup_rank_decks when the workflow needs provider-specific behavior.

Public tool prefixes are archidekt_, card_, commander_, combo_, deck_, playgroup_, server_, source_, wincon_, and workspace_. Compatibility aliases from older 0.x releases are intentionally not exposed.

Useful resources:

• Workspace data: mtg://workspace/{workspaceId},

mtg://workspace/{workspaceId}/summary, mtg://workspace/{workspaceId}/intent.

• Usage guides: mtg://scryfall/syntax-cheatsheet,

mtg://formats/{format}/deck-rules, mtg://usage/workspace-selection, mtg://usage/simulation-tool-selection, mtg://usage/operation-modes, mtg://usage/deck-intent.

• Status: mtg://config/effective, mtg://sources/status,

mtg://server/info, mtg://providers/{provider}/auth-status.

Built-in prompts cover brewing, tuning, Commander common-card and win-condition evidence, cost reduction, power increases or reductions, Commander bracket reduction, mana-base work, land-drop risk, consistency, local meta tuning, new-card swaps, missing combo pieces, goldfishing, goal-focused packages, and rules/rulings checks.

For Playgroup-aware tuning, deck_score_cards_for_playgroup_meta scores explicit candidate names with candidateSource=explicit-cards, or cards in excluded workspace categories with candidateSource=excluded-workspace-cards, with visible factor scores for plan fit, deterministic performance delta, local-meta coverage, self-harm, price/bracket constraints, and evidence confidence. Playgroup decks are ranked from fetched game participations; Archidekt decklists are imported read-only when Playgroup exposes an Archidekt URL.

Simulation results include the resolved simulation profile, why that profile was chosen, route evidence, and warnings when a claim comes from fallback heuristics. See docs/simulation-profiles.md for the compact profile, deck-intent, and route syntax reference.

Several mutation and lookup tools default to bounded output so repeated agent work does not flood context. Use detailLevel:"full" when you need full workspace or facet payloads from tools such as deck_refresh_card_metadata, deck_plan_apply, category edits, mutation tools, or card_facets_get. Performance analysis tools preserve backward-compatible raw payloads by default; use detailLevel:"normal" or detailLevel:"summary" on deck_analyze_performance and deck_plan_compare_performance for bounded key metrics, failed scenarios, stranded cards, warnings, and command-zone context. Use mtg://usage/simulation-tool-selection when choosing between Stats Lab performance, goldfish sequence, board projection, win-turn estimate, workspace goldfish comparison, and Archidekt-backed comparison tools.

Deck Intent

Deck intent is optional text stored in a workspace description, and in the Archidekt deck description when writeback is enabled. Use deck_intent_suggest, deck_intent_get, deck_intent_set, and deck_intent_clear.

Small example:

MTG MCP Deck Intent
Version: 2
Format: commander
Commander: Teysa Karlov
Goal: Aristocrats value with resilient sacrifice engines
Power Level: tuned-casual
Power Target: tuned casual
Heuristic Profile: command-zone-template
Simulation Profile: value
Archetype Tags: aristocrats, tokens, graveyard
Local Meta: graveyards, go-wide tokens
Budget: prefer upgrades under $10

Build Targets
Ramp: 8-10
Draw: 10-12
Interaction: 10-14

Simulation
Mulligan Style: multiplayer-london
Hold Interaction From Turn: 3
Minimum Interaction Held: 1
Prefer Commander On Curve: true

Win Routes
Blood Artist Drain: requires commander, tag:aristocrats, tokens>=4; earliest turn 6; kind finisher

Avoid
- deterministic infinite combos
End MTG MCP Deck Intent

Supported power levels are precon, casual, tuned-casual, high-power, and cedh. Supported heuristic profiles are auto, commander-baseline, command-zone-template, edhrec-foundation, mana-rich-39-land, fifty-mana-sources, package-8x8, package-7x9, package-9x7, seventy-five-percent, cedh-turbo, cedh-midrange, cedh-stax, cedh-tempo, archetype-landfall, archetype-sea-monsters, archetype-enchantments, and archetype-go-wide. Supported simulation profiles are auto, neutral, aggro, combo, control, value, big-mana, and stax. Package templates are none, 8x8, 7x9, and 9x7.

For the full syntax, read mtg://usage/deck-intent or docs/simulation-profiles.md.

How It Works

mtg-mcp runs as a stdio MCP server. It stores local workspaces, edit plans, annotations, and cache data under MTGMCP__DATA_DIR.

Archidekt writeback has two gates: the server must run in apply mode, and the deck must be opened with writeback enabled. Multi-card Archidekt edits require or create a checkpoint before applying a plan.

Card-only edit plans are applied as a single batch. Commander deck-size checks use the final included card count, so equal add/remove swaps can add before cutting as long as the finished deck remains legal.

Source-backed recommendations query structured APIs on demand and cache source facts under the recommendation source cache directory. The cache stores source facts, not final recommendations or prompt rationale. Pass bypassCache=true to supported tools to bypass fresh cache entries for one call.

The source policy is API-only: official/documented APIs and explicitly allowed unofficial structured JSON endpoints may be used, but mtg-mcp does not scrape HTML, parse page markup, or use browser automation for source data.

Development

Fresh Checkout

Development is supported without installing the pinned SDK globally. From a fresh checkout, run the bootstrap script for your platform. It installs Go Task under .tools when needed, then delegates to task setup, which installs the pinned .NET SDK under .dotnet, restores dotnet tools, and restores NuGet packages:

./bootstrap.sh

.\bootstrap.ps1

You can pass any Task workflow through bootstrap:

./bootstrap.sh test

After setup, use the same Task workflows as CI:

task test
task lint
task install:local
task install:local:cleanup

On Linux, scripts/setup-linux.sh remains available when you also want local PowerShell and repo-local .NET/NuGet cache paths. Source scripts/env-linux.sh after using it to carry those paths into future shells.

task install:local publishes the current host runtime by default, so Linux uses linux-x64 or linux-arm64 depending on the machine. Override it only when cross-publishing:

task publish:runtime RUNTIME=linux-x64

For a system-wide setup instead of the local bootstrap, install the .NET SDK, Task CLI, and PowerShell versions listed in versions.env, then run task setup. You also need curl, which is used by the setup script and optional Moxfield HTTP fallback.

Common Workflows

Use Taskfile.yml for common workflows:

task test
task lint
task install:local
task install:local:cleanup

task install:local packs the current checkout using the package version in server.json. It refreshes the global .NET tool from that freshly packed local package when the existing tool store is unlocked, publishes a self-contained binary, and copies it to the configured local MCP command path when one is found. If the global tool or configured executable is locked by a running MCP process, it leaves the locked file in place, writes a versioned binary beside it, and updates the Codex MCP config for the next server start. Pass LOCAL_VERSION=... only when you need an explicit one-off package version.

task install:local:cleanup removes old unlocked versioned local binaries while keeping the currently configured MCP command path.