Scryfall MCP Server
Scryfall MCP 服务器
基于 Scryfall 的 MCP 服务器,用于万智牌的搜索、规则查询、定价、系列发现和套牌构建工作流。
该项目目前支持:
stdio作为本地 MCP 客户端的主要传输方式通过
src/http.ts实现本地优先的可流式 HTTP14 个 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_cardbuild_deck
Related MCP server: MTG-MCP
传输方式
STDIO
推荐用于 Claude Desktop、Codex、MCP Inspector 和大多数本地 MCP 客户端。
npm run devnpm start可流式 HTTP
作为单独的入口点提供,适用于本地或受控环境。
npm run dev:httpnpm 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_AGENTRATE_LIMIT_MSRATE_LIMIT_QUEUE_MAXSCRYFALL_TIMEOUT_MSCACHE_MAX_SIZECACHE_MAX_MEMORY_MBLOG_LEVELNODE_ENVHEALTHCHECK_DEEPHTTP_HOSTHTTP_PORTHTTP_MCP_PATHHTTP_HEALTH_PATHHTTP_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 toolsanalyze_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for I Want My MTG that enables conversational search of Magic: The Gathering cards/sets and inventory management via API tools.61418 npm1MIT
- AlicenseNot gradedqualityDmaintenanceA 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.1MIT
- AlicenseAqualityDmaintenanceMCP 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.4MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that searches and retrieves Magic: The Gathering card data from the Scryfall API.74,083 npmMIT