mtg-mcp

一个基于 Python 的极简模型上下文协议 (MCP) 服务器，向任何兼容 MCP 的 LLM 客户端提供 Magic: The Gathering 卡牌查询（以及健康检查）功能。

配套博文： 模型上下文协议教程：构建你的第一个服务器

该文章完整介绍了本仓库：什么是 MCP，这两个工具如何工作，从“第一天伪造”到“第二天真实”的 Scryfall 集成过程，以及如何将其连接到 Claude Desktop。

功能介绍

通过一个 Python 进程经由 MCP stdio 暴露两个工具：

• health.check — 返回服务器版本、当前 UTC 时间以及持久化存储在 streak.json 中的简单“学习连胜”计数器。这是最简单的工具，无外部依赖。

• mtg.card_lookup — 接收卡牌名称并返回卡牌的类型行、神谕文本、法术力值和图片 URL。调用 Scryfall 模糊名称查询端点。

mtg.card_lookup 的契约是预先设计好的；其实现经历了从伪造到真实的刻意演进过程。完整的规范驱动文档请参阅 docs/01-spec-scryfall-integration.md。

Related MCP server: Scryfall MCP Server

快速开始

git clone https://github.com/jabelk/mtg-mcp.git
cd mtg-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
python src/server.py

服务器默认通过 stdio 运行，并将阻塞等待 MCP 客户端连接。这是正常的——请将你的客户端指向命令 python src/server.py（使用绝对路径）以开始调用工具。

建议使用 Python 3.11 或更高版本。uvloop 是可选的，在 Windows 上会自动跳过。

连接到 Claude Desktop

在你的 claude_desktop_config.json 中添加一个条目：

{
  "mcpServers": {
    "mtg": {
      "command": "/absolute/path/to/mtg-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/mtg-mcp/src/server.py"]
    }
  }
}

解释器和脚本路径均请使用绝对路径；Claude Desktop 会自行启动服务器，因此 ~ 或相对路径将无法解析。保存后请完全退出并重新打开 Claude Desktop。

仓库布局

mtg-mcp/
├── src/
│   ├── server.py            # MCP server entry point — registers the two tools
│   └── tools/
│       ├── __init__.py
│       └── card_lookup.py   # Scryfall integration (Day-2 real implementation)
├── docs/
│   ├── 01-spec-scryfall-integration.md   # spec for the Day-1 → Day-2 swap
│   ├── 02-plan-scryfall-integration.md   # implementation plan
│   └── 03-lessons-learned.md             # retrospective
├── requirements.txt
├── LICENSE
└── README.md

logs/ 目录和 streak.json 在运行时创建。

第一天 → 第二天：本仓库的演进

mtg.card_lookup 的第一个版本返回的是硬编码的伪造响应（仅匹配名称 Atraxa）。从伪造开始的目的是为了验证连接——即 MCP 客户端能够找到工具、调用它并解析响应格式——而无需调试任何 HTTP 层。

一旦连接确认，同一个函数被切换为调用 Scryfall。函数签名、输入模式和返回格式均未改变。契约保持不变。这种演进正是配套博文的核心所在；切换规范位于 docs/01-spec-scryfall-integration.md，计划位于 docs/02-plan-scryfall-integration.md，回顾总结位于 docs/03-lessons-learned.md。

依赖项

mcp        # the official MCP Python SDK
uvloop     # faster event loop (skipped on Windows)
httpx      # HTTP client for the Scryfall call

本仓库未锁定版本。如果你需要可重复性，请在安装时锁定版本。

许可证

MIT — 版权所有 (c) 2026 Jason Belk。

延伸阅读

• 配套文章：模型上下文协议教程：构建你的第一个服务器

• 官方 MCP 文档：modelcontextprotocol.io

• Anthropic 的 MCP 发布公告：anthropic.com/news/model-context-protocol

• Scryfall API：scryfall.com/docs/api