Scryfall MCP Server

Scryfall MCP服务器

Scryfall支持的魔术MCP服务器：收集搜索、规则查找、定价、集合发现和甲板建造工作流。

该项目目前支持：

• stdio 作为本地MCP客户端的主要传输方式
• 本地第一流式HTTP通过 src/http.ts
• 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：检查斗殴和标准斗殴指挥官的合法性。
• analyze_deck_composition：评估甲板列表的曲线、颜色和结构问题。
• suggest_mana_base：根据颜色要求推荐土地数量和固定方案。

资源

• card-database://bulk：缓存的Oracle批量快照。
• set-database://all：缓存的集合列表快照。

提示

• analyze_card
• build_deck

运输

工作室

建议用于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 默认情况下
• 服务 POST|GET|DELETE 上 /mcp
• 服务 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.示例 对于规范值。当前使用的主要变量有：

• 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_SESSION_IDLE_MS
• HTTP_SESSION_CLEANUP_INTERVAL_MS
• HTTP_ALLOWED_ORIGINS

操作说明：

• Scryfall API调用由共享速率限制器进行全局序列化。批处理工具可以安排多个本地查找，但上游的Scryfall请求完成仍然是按设计一次完成一个。
• 一般API端点的默认起搏为100 ms，Scryfall的2/sec卡端点的默认步幅至少为500 ms： /cards/search, /cards/named, /cards/random，以及 /cards/collection.
• HTTP 429响应不会自动重试。服务器记录Scryfall的限制窗口并延迟下一个请求启动，以便调用者可以决定是否重试。
• CACHE_MAX_MEMORY_MB 控制大型内存快照，包括 card-database://bulk，可以保留。批量资源首先将流重建为临时文件；超大快照保留在磁盘上进行热读取，而不是保留在内存中。
• 卡片详细信息输出包括Scryfall源链接和艺术家归因（如果可用）。呈现Scryfall图像URL的消费者应保护版权、艺术家和源上下文，不应裁剪、扭曲、重新着色、添加水印或暗示卡片图像的所有权。
• 牌组列表分析首先精确解析牌名，然后退回到模糊查找以查找确切的失误，并在响应中报告任何模糊的解决方案。
• 当Scryfall限制底层卡查找时，卡组缩放工具可能会在消息后返回部分分析或显式重试。
• 流式HTTP会话在以下时间过期 HTTP_SESSION_IDLE_MS 并由以下人员检查 HTTP_SESSION_CLEANUP_INTERVAL_MS.

本地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 当焦点是一个主题而不是一张可解决的卡片时。当焦点转移到一张卡上时，该工具会推断出该卡的颜色标识，并根据请求的合法性、竞技场可用性和颜色标识过滤最终结果。

analyze_deck_composition

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

Claude桌面集成

将构建的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，Scryfall2/sec卡端点的最小间隔为500 ms。
• 搜索响应、卡详细信息、价格、集合和批量快照都以有界内存限制进行缓存。
• 大容量卡资源流通过磁盘重建，并存储预序列化的快照，以保持重复读取的成本低廉。
• 集合过滤是从一个规范缓存中派生出来的 /sets 数据集，以避免不正确的过滤缓存重用。
• 健康检查可通过以下方式进行 ScryfallMCPServer.healthCheck() 以及HTTP /health 终点。
• 如果MCP连接器报告JSON-RPC/SSE反序列化错误，请将其与原始HTTP烟雾路径进行比较：

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

如果烟雾命令成功，则将连接器错误文本和烟雾输出一起捕获；它将本地端点框架与特定于连接器的解析分开。

文档地图

当前真相文档来源：

• 目的.md
• 贡献.md
• 安全.md
• SCRYFALL_团结.md

许可证

麻省理工学院