mcpField
M
MTG MCP Server

MTG MCP Server

本地服务
github.com游戏娱乐201 周前更新
代码仓库访问官网

关于 MTG MCP Server

MTG MCP Server 是面向万智牌（Magic: The Gathering）的 MCP 服务，提供卡牌检索、combo 查询、选秀数据分析和 Commander 工具。它面向希望让 AI 助手查询万智牌数据的玩家与构筑者，数据来自多个公开来源。

主要功能

  1. 01Scryfall 语法卡牌搜索与价格查询
  2. 02Commander Spellbook combo 查询与 bracket 估算
  3. 0317Lands 选秀数据与卡牌胜率分析
  4. 04EDHREC Commander 热门卡与协同数据
  5. 05Moxfield 牌表获取与 Spicerack 赛事数据

适用场景

  1. 01为 Commander 牌组筛选预算升级卡
  2. 02在选秀中按数据对卡包中的卡牌排序
  3. 03检查 Modern 牌表是否合法并查看禁限表

MCP 相关

该项目是一个 MCP 服务，向 MCP 客户端暴露 69 个工具、19 个提示词和 21 个资源，涵盖卡牌数据、combo、选秀、构筑与规则查询。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "j4th-mtg": {
      "command": "uvx",
      "args": [
        "mtg-mcp-server"
      ],
      "env": {
        "MTG_MCP_TRANSPORT": "<MTG_MCP_TRANSPORT>",
        "MTG_MCP_HTTP_PORT": "<MTG_MCP_HTTP_PORT>",
        "MTG_MCP_LOG_LEVEL": "<MTG_MCP_LOG_LEVEL>",
        "MTG_MCP_ENABLE_17LANDS": "<MTG_MCP_ENABLE_17LANDS>",
        "MTG_MCP_ENABLE_EDHREC": "<MTG_MCP_ENABLE_EDHREC>",
        "MTG_MCP_ENABLE_BULK_DATA": "<MTG_MCP_ENABLE_BULK_DATA>",
        "MTG_MCP_SCRYFALL_RATE_LIMIT_MS": "<MTG_MCP_SCRYFALL_RATE_LIMIT_MS>",
        "MTG_MCP_BULK_DATA_REFRESH_HOURS": "<MTG_MCP_BULK_DATA_REFRESH_HOURS>",
        "MTG_MCP_ENABLE_RULES": "<MTG_MCP_ENABLE_RULES>",
        "MTG_MCP_DISABLE_CACHE": "<MTG_MCP_DISABLE_CACHE>",
        "MTG_MCP_ENABLE_MOXFIELD": "<MTG_MCP_ENABLE_MOXFIELD>",
        "MTG_MCP_ENABLE_SPICERACK": "<MTG_MCP_ENABLE_SPICERACK>",
        "MTG_MCP_ENABLE_MTGGOLDFISH": "<MTG_MCP_ENABLE_MTGGOLDFISH>"
      }
    }
  }
}
启动命令uvx mtg-mcp-server
需要配置的环境变量
MTG_MCP_TRANSPORTServer transport — 'stdio' (default) or 'http'
MTG_MCP_HTTP_PORTHTTP port when transport is 'http'
MTG_MCP_LOG_LEVELLogging level — DEBUG, INFO, WARNING, or ERROR
MTG_MCP_ENABLE_17LANDSEnable 17Lands draft analytics backend
MTG_MCP_ENABLE_EDHRECEnable EDHREC commander metagame backend (uses undocumented endpoints)
MTG_MCP_ENABLE_BULK_DATAEnable Scryfall Oracle Cards bulk data for rate-limit-free lookups (~30 MB download)
MTG_MCP_SCRYFALL_RATE_LIMIT_MSMinimum delay between Scryfall API calls in milliseconds
MTG_MCP_BULK_DATA_REFRESH_HOURSHours between Scryfall bulk data refreshes
MTG_MCP_ENABLE_RULESEnable Comprehensive Rules engine for rules lookup and keyword tools
MTG_MCP_DISABLE_CACHEDisable in-memory TTL caching (useful for testing)
MTG_MCP_ENABLE_MOXFIELDEnable Moxfield deck search and import backend (reverse-engineered API)
MTG_MCP_ENABLE_SPICERACKEnable Spicerack tournament results backend
MTG_MCP_ENABLE_MTGGOLDFISHEnable MTGGoldfish metagame data backend (HTML scraping)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypimtg-mcp-server3.0.0

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

mtg-mcp-server

CI PyPI Python 3.12+ License: MIT codecov CodeQL Smithery Dependabot uv Ruff

69 个工具、19 个提示词和 21 个资源，让 AI 助手能够深入访问万智牌内容——包括卡牌数据、组合技、轮抽分析、指挥官赛制环境、竞技构筑、备牌策略、套牌构筑、规则引擎等。可与 Claude Code、Claude Desktop 或任何 MCP 客户端配合使用。

基于 Scryfall、Commander Spellbook、17Lands、EDHREC、Moxfield、Spicerack 和 MTGGoldfish 提供的数据构建。详情和使用条款请参阅数据来源与署名。

目录

  • 你可以做什么 — 示例提示词和实际工具输出
  • 安装 — 托管服务、Claude Code、Claude Desktop、PyPI、开发环境
  • 配置 — 环境变量和功能标志
  • 工具 — 涵盖 13 个领域的全部 69 个工具
  • 架构 — FastMCP 3.x 挂载系统
  • 技术栈 — Python 3.12+、FastMCP、httpx、Pydantic
  • 开发 — 用于测试、代码检查和类型检查的 mise 命令
  • 文档 — 实用指南、架构、工具参考等
  • 状态 — 当前工具和测试数量
  • 数据来源与署名 — Scryfall、Spellbook、17Lands、EDHREC、Moxfield、Spicerack、MTGGoldfish

你可以做什么

向 AI 助手提出以下问题，它会自动使用 MTG 工具：

指挥官

  • “介绍一下 Muldrotha 作为指挥官的所有信息”
  • “我预算低于 $5 的 Atraxa 套牌有哪些最佳升级？”
  • “比较一下 Muldrotha、Meren 和 Karador 作为坟场指挥官的表现”

轮抽与限制赛

  • “Foundations 轮抽中最好的普通牌有哪些？”
  • “为我的轮抽补充包中的这些牌排序：Bitter Triumph、Monstrous Rage、Torch the Tower”
  • “用这个牌池组一套现开套牌：[列表]”

套牌构筑

  • “验证我的 Modern 套牌列表”
  • “为我的三色指挥官套牌推荐一套法术力基础”
  • “找出与 Golgari 献祭主题有协同作用的牌”

规则

  • “死触和践踏如何互动？”
  • “判定这个战斗场景：我的 3/3 先攻生物阻挡了对方具有践踏的 5/5 生物”

构筑赛

  • “现在 Modern 赛制的环境如何？”
  • “展示 Modern 赛制中主流的 Boros Energy 套牌列表”
  • “为这套 Pioneer 套牌构建一套备牌”
  • “为我的套牌提供一份对阵 Azorius Control 的备牌指南”
查看实际效果

“比较 Muldrotha、Meren 和 Karador 这几位墓地指挥官”

                     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%)

“Foundations 补充包轮抓中有哪些最好的普通牌？”

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%) ...

更多包含真实工具输出的示例，请参阅 Cookbook。

安装

无需 API 密钥——所有数据源均为公开数据。

托管（零配置）

最快的入门方式。无需安装 Python。支持在移动设备上使用。

通过界面（Claude Desktop 或 claude.ai）：Settings → Connectors → Add custom connector → 粘贴 URL：

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

通过配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "mtg": {
      "type": "url",
      "url": "https://mtg-mcp-server.fastmcp.app/mcp"
    }
  }
}
Claude Code
claude mcp add mtg -- uvx mtg-mcp-server

也可以通过界面操作：Settings → MCP Servers → Add server → 输入 uvx mtg-mcp-server 作为命令。

Claude Desktop（本地）

在你的计算机上运行。需要 Python 3.12+。

{
  "mcpServers": {
    "mtg": {
      "command": "uvx",
      "args": ["mtg-mcp-server"]
    }
  }
}
PyPI
# 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
开发
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 配置：

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

配置

所有设置均使用 MTG_MCP_ 环境变量。采用合理的默认值，开箱即用。

# 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

请参阅 .env.example，了解所有可用选项，包括基础 URL、速率限制和缓存设置。

工具

涵盖 13 个领域的 69 个工具。完整的输入/输出详情请参阅 docs/TOOL_DESIGN.md。

牌张数据（scryfall_*）
工具说明
search_cards使用完整的 Scryfall 语法搜索（f:commander id:sultai t:creature）
card_details按准确或模糊名称获取完整牌张数据
card_price当前美元、欧元和闪卡价格
card_rulings官方裁定与说明
set_info按代码获取系列元数据
whats_new最近发布或预览的牌张
批量数据（bulk_*）
工具说明
card_lookup不受速率限制的按准确名称牌张查询
card_search按名称、类型或 Oracle 文本搜索
format_legality检查牌张在某赛制中是否合法
format_search搜索特定赛制中合法的牌张
format_staples按 EDHREC 排名列出某赛制中使用最多的牌张
ban_list某赛制的禁限牌
card_in_formats查看牌张在所有赛制中的合法性
random_card随机牌张，可按赛制或类型筛选
similar_cards按类型、关键字或法术力费用查找相似牌张
连招（spellbook_*）
工具说明
find_combos按牌张名称和颜色特征搜索连招
combo_details按 ID 获取逐步连招说明
find_decklist_combos查找牌表中包含的连招
estimate_bracket估算牌表的 Commander 档位
轮抓分析（draft_*）
工具说明
card_ratings获取某系列牌张的胜率和轮抓数据（17Lands）
archetype_stats获取某系列按双色组合统计的胜率
Commander 环境（edhrec_*）
工具说明
commander_staples获取某指挥官使用最多的牌张及其协同分数
card_synergy获取某牌张与特定指挥官的协同数据
牌表（moxfield_*）
工具说明
decklist按牌表 ID 或 URL 获取完整牌表
deck_info牌表元数据（名称、赛制、作者、日期）
search_decks按赛制、关键词或排序方式搜索公开牌表
user_decks列出用户的公开牌表
锦标赛数据（spicerack_*）
工具说明
recent_tournaments获取某竞技赛制的近期锦标赛
tournament_results获取特定锦标赛的完整排名
format_decklists获取近期锦标赛中排名靠前的牌表
Metagame (goldfish_*)
工具描述
metagame竞争赛制的当前环境构成
archetype_list某个构筑思路的示例牌表
format_staples某个赛制中最常用的牌及其牌组收录率
deck_price某个构筑思路牌组的纸质牌估算价格
指挥官工作流
工具描述
commander_overview汇总所有来源的完整指挥官档案
evaluate_upgrade评估一张牌是否值得加入牌组
card_comparison针对某位指挥官并排比较 2-5 张牌
budget_upgrade按协同度/美元排名的预算升级建议
commander_comparison并排比较 2-5 位指挥官
color_identity_staples某种颜色身份的所有指挥官中最常用的牌
构筑牌组
工具描述
theme_search查找符合某种机制或部族主题的牌
build_around检测关键牌的协同效应并查找配合牌
complete_deck分析不完整牌表的缺口并提供建议
tribal_staples某种颜色身份下适用于某个生物类别的最佳牌
precon_upgrade分析预组牌组并建议替换组合
suggest_cuts找出牌表中最弱、适合移除的牌
deck_analysis全面检查牌表状况（曲线、颜色、组合技、预算）
deck_validate根据赛制构筑规则验证牌表
suggest_mana_base根据颜色符号分布推荐地牌
price_comparison比较多张牌的价格
轮抽工作流
工具描述
draft_pack_pick使用 17Lands 数据为轮抽补充包中的牌排序
set_overview某个赛制中的顶尖普通牌/非普通牌及陷阱稀有牌
sealed_pool_build根据现开牌池推荐最佳的 40 张牌构筑
draft_signal_read根据轮抽选牌判断开放的颜色
draft_log_review按选牌顺序复盘已完成的轮抽并评分
构筑赛制工作流
工具描述
rotation_check标准赛制轮换状态及即将轮换的牌
metagame_snapshot带价格信息的分级赛制环境构成
archetype_decklist竞争性构筑思路的常规牌表
archetype_comparison并排比较 2-4 种构筑思路
format_entry_guide进入竞争赛制的新手指南
suggest_sideboard为牌组推荐 15 张备牌
sideboard_guide针对特定对局的备牌进出计划
sideboard_matrix常见对局的备牌矩阵
规则引擎
工具描述
rules_lookup按编号或关键词查询规则
keyword_explain通过规则和示例牌解释关键词
rules_interaction两种机制的互动方式及规则引文
rules_scenario游戏情境的规则框架
combat_calculator逐步讲解战斗阶段及关键词互动

架构

基于 FastMCP 3.x 构建。每个数据源都是独立的子服务，并挂载到一个统一的协调器中：

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)

服务是纯异步 API 客户端。提供方会注册 MCP 工具。工作流可跨服务组合，并容忍部分故障。完整说明请参阅 docs/ARCHITECTURE.md。

技术栈

运行时Python 3.12+、uv
MCPFastMCP 3.2.x
HTTPhttpx（异步）
验证Pydantic v2
日志记录structlog
工具链mise、ruff、ty（Astral）
测试pytest、respx、pytest-asyncio
HTML 解析selectolax

开发

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

文档

文档内容
COOKBOOK.md使用指南——Commander、套牌草稿、套牌构建、规则工作流
TOOL_DESIGN.md全部 69 个工具、19 个提示词和 21 个资源的完整参考
ARCHITECTURE.md技术架构、FastMCP 模式和设计决策
SERVICE_CONTRACTS.md各后端的 API 端点、速率限制和响应格式
DATA_SOURCES.md所有数据源及其身份验证、稳定性和访问模式
CACHING_DESIGN.mdTTL 缓存策略和 Scryfall 批量数据设计
CONTRIBUTING.md开发环境设置、TDD 工作流、代码风格和 PR 流程
CHANGELOG.md按 Keep a Changelog 格式记录的版本历史

状态

69 个工具、19 个提示词、21 个资源模板。1340 项测试，覆盖率为 88%。

阶段内容状态
0项目脚手架已完成
1Scryfall 后端（4 个工具）已完成
2Spellbook、17Lands 和 EDHREC 后端（9 个工具）已完成
3工作流工具——Commander、套牌草稿、套牌（4 个工具）已完成
4TTL 缓存 + Scryfall 批量数据提供程序（2 个工具）已完成
5分析与比较工作流、提示词、资源（4 个工具）已完成
分支 A结构化输出、规则引擎、验证工具（17 个工具）已完成
分支 B赛制工作流——套牌构建、Commander 深度分析、限制赛、构筑赛（11 个工具）已完成
MoxfieldMoxfield 套牌列表提供程序（4 个工具）已完成
Spicerack锦标赛结果提供程序（3 个工具）已完成
MTGGoldfish环境数据提供程序（4 个工具）已完成
v2.3.0环境工作流、备牌工具、Moxfield 搜索（9 个工具）已完成

数据来源与署名

本项目整合了来自多个第三方服务的数据：

  • Scryfall——卡牌数据库、价格、裁定、搜索、批量数据（API 指南）
  • Commander Spellbook——组合技搜索、强度等级估算（MIT 许可证）
  • 17Lands——限制赛卡牌评分、套牌原型胜率（使用指南）
  • EDHREC——Commander 常用卡牌、协同评分（未公开文档的端点，受功能标志控制）
  • Moxfield——公开套牌列表和套牌搜索（通过逆向工程获得的 API，受功能标志控制）
  • Spicerack——锦标赛结果和排名（有文档说明的 API）
  • MTGGoldfish——竞技环境数据、套牌原型、赛制常用卡牌（HTML 抓取，受功能标志控制）

完整的许可证文本和使用条款，请参阅 THIRD_PARTY_NOTICES.md。

免责声明

mtg-mcp-server 是根据 Fan Content Policy 获准发布的非官方粉丝内容。Wizards 未对其批准或背书。所用材料的部分内容归 Wizards of the Coast 所有。© Wizards of the Coast LLC。

许可证

MIT——请参阅 LICENSE

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。