Scryfall MCP Server
Scryfall MCP 서버
매직: 더 개더링 검색, 규칙 조회, 가격 확인, 세트 탐색 및 덱 구성 워크플로우를 위한 Scryfall 기반 MCP 서버입니다.
현재 프로젝트는 다음을 지원합니다:
로컬 MCP 클라이언트를 위한 기본 전송 수단으로
stdio지원src/http.ts를 통한 로컬 우선 Streamable 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) 및 스탠다드 브롤 사령관 적법성을 확인합니다.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 startStreamable 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서비스 제공HTTP_ALLOWED_ORIGINS가 설정되지 않은 경우 기본적으로 루프백이 아닌Origin헤더 거부
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를 포함한 대규모 메모리 내 스냅샷을 유지할 수 있는지 여부를 제어합니다. 크기가 초과된 대량 스냅샷은 현재 읽기에 대해 반환될 수 있지만, 메타데이터는 캐시되지 않았음을 보고합니다.덱 리스트 분석은 카드 이름을 정확히 먼저 확인한 다음, 정확히 일치하지 않는 경우 퍼지(fuzzy) 조회를 수행하고 응답에 퍼지 해결 결과를 보고합니다.
덱 규모 도구는 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를 전달하십시오. 초점이 카드로 해결되면 도구는 해당 카드의 색상 정체성을 추론하고 요청된 적법성, 아레나 가용성 및 색상 정체성에 따라 최종 결과를 필터링합니다.
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 요청 간 최소 100ms의 기본 간격으로 프로세스 내에서 강제됩니다.
검색 응답, 카드 세부 정보, 가격, 세트 및 대량 스냅샷은 제한된 메모리 내 한도로 캐시됩니다.
대량 카드 리소스는 반복적인 읽기를 저렴하게 유지하기 위해 미리 직렬화된 스냅샷을 저장합니다.
세트 필터링은 잘못된 필터링된 캐시 재사용을 방지하기 위해 하나의 표준 캐시된
/sets데이터셋에서 파생됩니다.상태 확인은
ScryfallMCPServer.healthCheck()및 HTTP/health엔드포인트를 통해 사용할 수 있습니다.MCP 커넥터가 JSON-RPC/SSE 역직렬화 오류를 보고하는 경우, 원시 HTTP 스모크 경로와 비교하십시오:
npm run dev:http:local
npm run smoke:http스모크 명령이 성공하면 커넥터 오류 텍스트와 스모크 출력을 함께 캡처하십시오. 그러면 로컬 엔드포인트 프레이밍과 커넥터별 파싱이 분리됩니다.
문서 맵
현재 진실의 원천(source-of-truth) 문서:
라이선스
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