Skip to main content
Glama
Scryfall MCP Server

Scryfall MCP Server

by bmurdock

Scryfall MCP 服务器

基于 Scryfall 的 MCP 服务器,用于万智牌的搜索、规则查询、定价、系列发现和套牌构建工作流。

该项目目前支持:

  • stdio 作为本地 MCP 客户端的主要传输方式

  • 通过 src/http.ts 实现本地优先的可流式 HTTP

  • 14 个 MCP 工具、2 个资源和 2 个提示词

它提供了什么

工具

  • search_cards:运行 Scryfall 卡牌搜索,支持分页、排序和可选的价格过滤。

  • get_card:通过名称、系列/收藏编号或 Scryfall ID 获取单张卡牌。

  • get_card_prices:返回价格数据,支持可选的格式上下文和替代方案。

  • random_card:获取一张随机卡牌,支持可选过滤器。

  • search_sets:搜索并过滤万智牌系列。

  • query_rules:在本地综合规则文件中进行上下文搜索。

  • build_scryfall_query:将自然语言转换为可解释的 Scryfall 查询。

  • search_format_staples:查找特定赛制的必备卡牌和常用卡牌。

  • search_alternatives:查找更便宜、升级版或类似的卡牌。

  • find_synergistic_cards:为卡牌、主题或原型查找协同组件。

  • batch_card_analysis:分析多张卡牌的合法性、价格、协同效应或构成。

  • validate_brawl_commander:检查 Brawl 和标准 Brawl 指挥官的合法性。

  • analyze_deck_composition:评估套牌列表的法术力曲线、颜色和结构问题。

  • suggest_mana_base:根据颜色需求推荐地牌数量和法术力调色方案。

资源

  • card-database://bulk:缓存的 Oracle 批量快照。

  • set-database://all:缓存的系列列表快照。

提示词

  • analyze_card

  • build_deck

Related MCP server: MTG-MCP

传输方式

STDIO

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

npm run dev
npm start

可流式 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 行为:

  • 默认绑定到 127.0.0.1

  • 在 /mcp 上提供 POST|GET|DELETE 服务

  • 提供 GET /health 服务

  • 默认拒绝非回环 Origin 标头,除非设置了 HTTP_ALLOWED_ORIGINS

HTTP 入口点目前很有用,但文档描述较为保守。此处并未将其作为公共托管方案展示。

设置

先决条件

  • Node.js 18+

  • npm

安装

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

验证

npm run lint
npm run type-check
npm test

构建

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 lint
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_ALLOWED_ORIGINS

操作说明:

  • Scryfall API 调用由共享速率限制器全局序列化。批量工具可能会调度多个本地查找,但上游 Scryfall 请求的完成设计为一次一个。

  • HTTP 429 响应不会自动重试。服务器会记录 Scryfall 的限流窗口并延迟下一个请求的开始,以便调用者决定是否重试。

  • CACHE_MAX_MEMORY_MB 控制是否可以保留大型内存快照(包括 card-database://bulk)。超大的批量快照仍可返回以供当前读取,但元数据将报告它们未被缓存。

  • 套牌列表分析首先精确解析卡牌名称,如果未找到则回退到模糊查找,并在响应中报告任何模糊解析结果。

  • 当 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 请求之间的默认最小间隔为 100 毫秒。

  • 搜索响应、卡牌详情、价格、系列和批量快照均在内存限制内进行缓存。

  • 批量卡牌资源存储预序列化的快照,以降低重复读取的成本。

  • 系列过滤源自一个规范的缓存 /sets 数据集,以避免错误地重用过滤后的缓存。

  • 健康检查可通过 ScryfallMCPServer.healthCheck() 和 HTTP /health 端点进行。

  • 如果 MCP 连接器报告 JSON-RPC/SSE 反序列化错误,请将其与原始 HTTP 冒烟路径进行比较:

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

如果冒烟测试命令成功,请同时捕获连接器错误文本和冒烟测试输出;这将有助于区分本地端点框架与连接器特定的解析问题。

文档地图

当前的权威文档:

许可证

MIT

Available Tools

14 tools
analyze_deck_compositionC

Analyze deck composition, mana curve, card types, and provide balance recommendations

Inputs: deck_list (required), commander, format, strategy.

batch_card_analysisC

Analyze multiple cards for legality, prices, synergies, or deck composition

Inputs: analysis_type (required), card_list (required), currency, format, +2 more.

build_scryfall_queryB

Convert natural language requests into optimized Scryfall search queries with explanations and alternatives

Inputs: natural_query (required), explain_mapping, format, include_alternatives, +4 more.

find_synergistic_cardsC

Find cards that synergize with a specific card, theme, or archetype

Inputs: focus_card (required), arena_only, exclude_colors, format, +4 more.

get_cardB

Get detailed information about a specific Magic: The Gathering card by name, set code+number, or Scryfall ID

Inputs: identifier (required), face, include_image, lang, +1 more.

get_card_pricesB

Get current price information for a Magic: The Gathering card by name, set/number, or Scryfall ID

Inputs: card_identifier (required), currency, format_context, include_alternatives, +1 more.

query_rulesC

Search Magic: The Gathering comprehensive rules for specific interactions and rule clarifications

Inputs: query (required), context_lines, exact_match, section.

random_cardB

Get a random Magic: The Gathering card, optionally filtered by format or search criteria

Inputs: archetype, exclude_reprints, format, price_range, +3 more.

search_alternativesB

Find budget alternatives, upgrades, or functionally similar cards

Inputs: direction (required), target_card (required), format, limit, +3 more.

search_cardsA

Search for Magic: The Gathering cards using Scryfall search syntax. Supports complex queries with operators like color:, type:, set:, etc.

Inputs: query (required), arena_only, direction, format, +8 more.

search_format_staplesC

Find format staples, meta cards, and role-specific cards for competitive play

Inputs: format (required), color_identity, limit, max_price, +2 more.

search_setsC

Search for Magic: The Gathering sets with optional filtering by name, type, and release dates

Inputs: query, released_after, released_before, type.

suggest_mana_baseC

Suggest optimal mana base composition and land recommendations for a deck

Inputs: color_requirements (required), average_cmc, budget, color_intensity, +4 more.

validate_brawl_commanderB

Validate if a card can be a legal commander in Brawl or Standard Brawl formats

Inputs: card_identifier (required), format (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no significant overlap. For example, get_card retrieves a single card, search_cards handles complex queries, and analyze_deck_composition focuses on deck analysis, making misselection unlikely.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, such as get_card, search_cards, and analyze_deck_composition. This predictability aids in agent understanding and usage.

    Tool Count5/5

    With 14 tools, the server is well-scoped for Magic: The Gathering card and deck management. Each tool serves a specific function, from card retrieval to deck analysis, without feeling excessive or insufficient.

    Completeness5/5

    The tool surface comprehensively covers the domain, including card search, price checks, deck analysis, rules queries, and format validation. There are no obvious gaps, supporting full agent workflows for MTG-related tasks.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for I Want My MTG that enables conversational search of Magic: The Gathering cards/sets and inventory management via API tools.
      61
      418 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive Model Context Protocol server that provides AI assistants with rich Magic: The Gathering information, including card data, comprehensive rules, EDHREC recommendations, combo interactions, and intelligent Commander deck generation.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for searching and retrieving Magic: The Gathering card information via the Scryfall API, with support for field presets, multiple output formats, and automatic rate limiting.
      4
      MIT