Skip to main content
Glama
Scryfall MCP Server

Scryfall MCP Server

by bmurdock

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_card

  • build_deck

Related MCP server: MTG-MCP

전송 수단

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 동작:

  • 기본적으로 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_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를 포함한 대규모 메모리 내 스냅샷을 유지할 수 있는지 여부를 제어합니다. 크기가 초과된 대량 스냅샷은 현재 읽기에 대해 반환될 수 있지만, 메타데이터는 캐시되지 않았음을 보고합니다.

  • 덱 리스트 분석은 카드 이름을 정확히 먼저 확인한 다음, 정확히 일치하지 않는 경우 퍼지(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 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