Scryfall MCP Server

Scryfall MCP 服务

基于 Scryfall 的 MCP 服务，支持《Magic: The Gathering》搜索、规则查询、价格查询、系列发现和套牌构建工作流。

项目目前支持：

• stdio，作为本地 MCP 客户端的主要传输方式
• 通过 src/http.ts 提供本地优先的 Streamable HTTP
• 15 个 MCP 工具、3 个资源和 2 个提示词

提供的功能

工具

• search_cards：使用分页、排序和可选的价格筛选条件执行 Scryfall 卡牌搜索。
• get_card：按名称、系列／收藏编号或 Scryfall ID 获取一张卡牌。
• get_card_prices：返回价格数据，并可选提供赛制背景和替代选项。
• random_card：根据可选筛选条件获取一张随机卡牌。
• search_sets：搜索和筛选 Magic 系列。
• query_rules：结合上下文搜索本地完整规则文件。
• build_scryfall_query：将自然语言转换为可解释的 Scryfall 查询。
• search_format_staples：使用明确披露的价格和排序启发式方法，搜索符合赛制规则的候选卡牌；不使用赛事环境数据。
• search_alternatives：使用明确披露的价格、类别和法术力值启发式方法查找候选卡牌；结果未经验证，不保证是功能上的替代品或升级选项。
• find_synergistic_cards：查找与某张卡牌、主题或原型有协同作用的卡牌。
• batch_card_analysis：分析多张卡牌的合法性、价格、协同作用或构成。
• validate_brawl_commander：检查 Brawl 和 Standard Brawl 指挥官的合法性。
• analyze_deck_composition：评估套牌列表的法术力曲线、颜色和结构问题。
• suggest_mana_base：根据颜色需求推荐地牌数量和修色组合。
• show_card_search：渲染 ChatGPT Apps 小组件，以可视化方式展示 Scryfall 卡牌搜索结果。

资源

• card-database://bulk：缓存的 Oracle 批量快照。
• set-database://all：缓存的系列列表快照。
• ui://widget/card-search.html：供 show_card_search 使用的 ChatGPT Apps 小组件模板。

提示词

• analyze_card
• build_deck

传输方式

STDIO

推荐用于 Claude Desktop、Codex、MCP Inspector 和大多数本地 MCP 客户端。

npm run dev

npm start

Streamable HTTP

作为单独的入口点提供，适用于本地或明确受控的环境。

npm run dev:http

npm run start:http

用于本地 MCP 测试：

npm run dev:http:local
npm run smoke:http

冒烟测试会检查 /health，执行 MCP initialize，发送 notifications/initialized，并验证 tools/list。 测试还会调用有代表性的 validate_brawl_commander 和 search_cards 工具，以确保对本地 HTTP 端点的检查不止于功能发现。

HTTP 请求默认保留 1 MiB 的正文大小限制（HTTP_MAX_BODY_BYTES）。在 SDK 或工具验证之前，HTTP 入口点还会拒绝请求 JSON 中数组元素和对象键总数超过 10,000 的情况。此限制适用于整个请求，包括批量请求；此外，SDK 1.32.2 将 批量请求限制为最多 100 条消息。 该结构检查采用迭代方式，适用于本项目的低层 Server 处理程序；它不依赖可选启用的 McpServer.maxToolInputElements 选项。

当前 HTTP 行为：

• 默认绑定到 127.0.0.1
• 在 /mcp 上提供 POST|GET|DELETE
• 提供 GET /health
• 默认拒绝非回环地址的 Origin 标头，除非设置了 HTTP_ALLOWED_ORIGINS
• 当 HTTP_HOST 不是回环地址时，要求同时设置 HTTP_AUTH_TOKEN 和 HTTP_TRUST_PROXY_TLS=true；后者是运营方的声明，表示可信的 HTTPS 代理或隧道会保护明文监听器
• 使用 HTTP_MAX_SESSIONS 限制活动会话和正在初始化的会话数量（默认值为 100）

目前 HTTP 入口点很实用，但文档仍采取谨慎表述。此处并未将其作为面向公众托管的方案介绍。

ChatGPT 应用开发

HTTP MCP 端点可连接到 ChatGPT Developer Mode，作为本地应用原型。在回环地址上启动服务：

npm run dev:http:local

使用 HTTPS 隧道公开该本地端点：

ngrok http 3000

然后在 ChatGPT Developer Mode 中连接隧道提供的 https://.../mcp URL。更改工具描述符、widget 资源或元数据后，请刷新应用，让 ChatGPT 重新加载当前 MCP 接口。

当前面向 ChatGPT 的 widget 是 show_card_search，它会向模型返回简洁的 structuredContent，并在 ChatGPT 中渲染 ui://widget/card-search.html。该 widget 只读访问 Scryfall，使用 Scryfall 图片 URL，并将其 CSP 资源允许列表限定为 https://cards.scryfall.io。

设置

前置条件

• Node.js ^20.19.0、^22.13.0 或 >=24.0.0
• npm

安装

git clone https://github.com/bmurdock/scryfall-mcp.git
cd scryfall-mcp
npm install
cp .env.example .env

文档中列出的 npm run dev*、npm start 和 npm run inspector 命令会预加载 .env。显式设置的进程环境变量优先于该文件中的值。直接启动 dist/index.js 的 MCP 客户端应通过自身的 env 配置提供覆盖值。

验证

npm run lint
npm run type-check
npm test
npm run test:coverage

构建

npm run build

常用命令

npm run dev
npm run dev:http
npm start
npm run start:http
npm test
npm run test:watch
npm run test:ui
npm run test:coverage
npm run lint
npm run lint:fix
npm run type-check
npm run inspector

配置

请参阅 .env.example 获取规范值。目前实际使用的主要变量包括：

• SCRYFALL_USER_AGENT
• RATE_LIMIT_MS
• RATE_LIMIT_QUEUE_MAX
• SCRYFALL_TIMEOUT_MS
• CACHE_MAX_SIZE
• CACHE_MAX_MEMORY_MB
• LOG_LEVEL
• NODE_ENV
• HEALTHCHECK_DEEP
• HTTP_HOST
• HTTP_PORT
• HTTP_MCP_PATH
• HTTP_HEALTH_PATH
• HTTP_MAX_BODY_BYTES
• HTTP_SESSION_IDLE_MS
• HTTP_SESSION_CLEANUP_INTERVAL_MS
• HTTP_ALLOWED_ORIGINS
• HTTP_AUTH_TOKEN
• HTTP_TRUST_PROXY_TLS
• HTTP_MAX_SESSIONS

运维说明：

• Scryfall API 调用由共享速率限制器进行全局串行调度。批量工具可以安排多个本地查询，但按设计，向 Scryfall 发起的请求始终逐个完成。
• 默认间隔为通用 API 端点 100 毫秒；对于 Scryfall 每秒限 2 次的卡牌端点 /cards/search、/cards/named、/cards/random 和 /cards/collection，间隔至少为 500 毫秒。
• HTTP 429 响应不会自动重试。服务端会记录 Scryfall 的限流时段，并延迟启动下一次请求，以便调用方决定是否重试。
• CACHE_MAX_MEMORY_MB 控制是否保留大型内存快照，包括 card-database://bulk。批量资源重建会先流式写入临时文件；超大快照会留在磁盘上，供后续读取，而不会保留在缓存中。每个 MCP 资源响应仍会按资源协议要求，将完整的序列化批量数据载入内存，因此调用方应预留与响应大小成正比的内存。
• 系列快照每周刷新一次。在缓存容量允许的情况下，过期快照最多可保留四周，并在计划刷新失败时提供；计划刷新失败后会在五分钟后重试。
• 卡牌详情输出会在可用时包含 Scryfall 来源链接和艺术家署名。渲染 Scryfall 图片 URL 的使用方应保留版权、艺术家和来源信息，且不得裁剪、扭曲、重新着色或添加水印，也不得暗示拥有卡牌图片的所有权。
• 非英语 get_card 查询使用 Scryfall 的本地化系列／收藏编号端点。名称和 UUID 查询会先解析某个印刷版本，再请求该印刷版本的指定语言；若无可用译文，则返回查询错误。
• get_card_prices 使用独立的六小时缓存，与 24 小时的卡牌详情缓存相互独立。
• 套牌列表分析会先精确解析卡牌名称；未精确匹配时再回退到模糊查询，并在响应中报告模糊匹配的结果。输入上限为 64 KiB、100 个唯一名称、总计 10,000 张卡牌，以及每个条目最多 1,000 张。
• 取消 MCP 工具、提示词或资源读取时，会停止其排队中的 Scryfall 工作。如果某项查询或资源读取被另一个活跃调用方共享，则会继续执行，直到该调用方完成或取消。取消批量资源读取会停止数据流并清理未完成的快照；关闭服务时会等待活跃的批量重建完成清理。
• 客户端关闭输入时，stdio 服务会关闭。格式错误的 HTTP URL 或 Host 标头会返回 HTTP 400，但不会导致服务终止。
• 提示词验证错误会保留便于采取行动的错误消息，并使用 MCP 无效参数错误代码。上游提示词错误会包含安全的状态或重试信息。
• suggest_mana_base 会返回启发式土地数量和循环类别；仍需核实各张卡牌的合法性和颜色兼容性。所有已分配的栏位都会纳入计算；没有特定循环可用时，会使用通用修正类别。目前不支持特殊土地要求；非空的 special_requirements 输入会返回验证错误。
• Scryfall 对底层卡牌查询进行限流时，套牌规模工具可能会返回部分分析结果或明确的重试等待时间提示。
• 流式 HTTP 会话会在 HTTP_SESSION_IDLE_MS 后过期，并按 HTTP_SESSION_CLEANUP_INTERVAL_MS 进行检查。
• 请求中包含已过期或未知的 HTTP 会话 ID 时会返回 404；客户端应在不带旧 ID 的情况下初始化新会话以恢复。请求缺少必需的会话 ID 时会返回 400。
• 绑定到非回环地址的 HTTP 服务需要 Bearer 令牌身份验证，并要求 HTTP_TRUST_PROXY_TLS=true。这表示受信任的 HTTPS 代理或隧道会保护明文监听器。Origin 允许列表仍是额外的浏览器策略，并非身份验证机制。
• GET /health 是就绪状态检查：必需服务降级时会返回 HTTP 503，包括 Scryfall 断路器处于开启状态时。

本地 HTTP 启动示例：

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

示例工具调用

build_scryfall_query

{
  "natural_query": "blue counterspells under $20 for modern",
  "optimize_for": "precision"
}

search_cards

{
  "query": "c:r t:instant mv=1",
  "limit": 10,
  "order": "name"
}

search_sets

{
  "type": "expansion",
  "released_after": "2020-01-01"
}

find_synergistic_cards

{
  "focus_card": "Obeka, Splitter of Seconds",
  "synergy_type": "theme",
  "format": "commander",
  "color_identity": "UBR",
  "limit": 12
}

对于类似指挥官的工作流，如果焦点是一个无法解析为卡牌的主题，请传入 color_identity。如果焦点能解析为一张卡牌，工具会推断该卡牌的颜色标识，并根据所请求的合法性、Arena 可用性和颜色标识筛选最终结果。

analyze_deck_composition

{
  "deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
  "format": "modern",
  "strategy": "aggro"
}

Claude Desktop 集成

将构建好的 stdio 入口添加到 Claude Desktop 配置中。

macOS 路径：~/Library/Application Support/Claude/claude_desktop_config.json

Windows 路径：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/scryfall-mcp/dist/index.js"]
    }
  }
}

运维说明

• 限流在进程内实施：一般 Scryfall API 请求之间的默认最小间隔为 100 ms，Scryfall 每秒 2 次的卡牌端点请求之间的最小间隔为 500 ms。
• 搜索响应、卡牌详情、价格、系列和批量快照均采用有界内存缓存。
• 批量卡牌资源通过磁盘流式重建，并存储预序列化快照，以降低重复读取的开销。缓存保留量有上限，但生成批量资源响应仍需要在进程内存中存放完整的序列化响应文本。
• 系列筛选基于单一规范的缓存 /sets 数据集生成，以避免筛选后的缓存被错误复用。
• 可通过 ScryfallMCPServer.healthCheck() 和 HTTP /health 端点进行健康检查。
• 如果 MCP 连接器报告 JSON-RPC/SSE 反序列化错误，请将其与原始 HTTP 冒烟测试路径进行对比：

npm run dev:http:local
npm run smoke:http

如果冒烟测试命令成功，请同时记录连接器错误文本和冒烟测试输出；这样可以区分本地端点帧处理问题与连接器特定的解析问题。

文档索引

当前权威文档：

• PURPOSE.md
• CONTRIBUTING.md
• SECURITY.md
• SCRYFALL_COMPLIANCE.md

许可证

MIT