mtg-mcp

Magic: The Gathering 카드 조회(및 상태 확인) 기능을 MCP 호환 LLM 클라이언트에 노출하는 Python 기반의 최소형 Model Context Protocol 서버입니다.

블로그 게시물 동반 자료: Model Context Protocol 튜토리얼: 첫 번째 서버 구축하기

이 게시물은 본 저장소를 처음부터 끝까지 다룹니다: MCP란 무엇인지, 두 가지 도구가 어떻게 작동하는지, Day-1-가짜 → Day-2-실제 Scryfall 연동으로의 발전 과정, 그리고 Claude Desktop에 연결하는 방법을 설명합니다.

기능

MCP stdio를 통해 하나의 Python 프로세스에서 노출되는 두 가지 도구:

• health.check — 서버 버전, 현재 UTC 시간, 그리고 streak.json에 저장된 간단한 "학습 연속(learning streak)" 카운터를 반환합니다. 가장 단순한 형태의 도구이며 외부 의존성이 없습니다.

• mtg.card_lookup — 카드 이름을 입력받아 해당 카드의 유형 라인, 오라클 텍스트, 마나 값, 이미지 URL을 반환합니다. Scryfall 퍼지 이름 검색 엔드포인트를 호출합니다.

mtg.card_lookup의 계약(contract)은 먼저 설계되었으며, 구현은 가짜에서 실제 구현으로 의도적인 발전 과정을 거쳤습니다. 전체 사양 기반의 설명은 docs/01-spec-scryfall-integration.md를 참조하세요.

Related MCP server: Scryfall MCP Server

빠른 시작

git clone https://github.com/jabelk/mtg-mcp.git
cd mtg-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
python src/server.py

서버는 기본적으로 stdio를 통해 실행되며 MCP 클라이언트가 연결될 때까지 대기합니다. 이는 정상적인 동작입니다. 클라이언트에서 python src/server.py 명령(절대 경로 사용)을 가리켜 도구 호출을 시작하세요.

Python 3.11 이상을 권장합니다. uvloop는 선택 사항이며 Windows에서는 자동으로 건너뜁니다.

Claude Desktop에 연결하기

claude_desktop_config.json에 항목을 추가하세요:

{
  "mcpServers": {
    "mtg": {
      "command": "/absolute/path/to/mtg-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/mtg-mcp/src/server.py"]
    }
  }
}

인터프리터와 스크립트 모두 절대 경로를 사용하세요. Claude Desktop이 서버를 직접 실행하므로 ~나 상대 경로는 해석되지 않습니다. 저장 후 Claude Desktop을 완전히 종료했다가 다시 여세요.

저장소 구조

mtg-mcp/
├── src/
│   ├── server.py            # MCP server entry point — registers the two tools
│   └── tools/
│       ├── __init__.py
│       └── card_lookup.py   # Scryfall integration (Day-2 real implementation)
├── docs/
│   ├── 01-spec-scryfall-integration.md   # spec for the Day-1 → Day-2 swap
│   ├── 02-plan-scryfall-integration.md   # implementation plan
│   └── 03-lessons-learned.md             # retrospective
├── requirements.txt
├── LICENSE
└── README.md

logs/ 디렉토리와 streak.json은 런타임에 생성됩니다.

Day 1 → Day 2: 이 저장소의 발전 과정

mtg.card_lookup의 첫 번째 버전은 하드코딩된 가짜 응답(이름이 Atraxa인 경우에만 일치)을 반환했습니다. 가짜로 시작한 이유는 MCP 클라이언트가 도구를 찾고, 호출하고, 응답 형태를 파싱할 수 있는지 확인하여 HTTP 계층을 디버깅하기 전에 연결 상태를 증명하기 위함이었습니다.

연결이 확인된 후, 동일한 함수를 Scryfall을 호출하도록 교체했습니다. 함수 시그니처, 입력 스키마, 반환 형태는 변경되지 않았습니다. 계약은 유지되었습니다. 이러한 발전 과정이 동반 블로그 게시물의 핵심입니다. 교체를 위한 사양은 docs/01-spec-scryfall-integration.md에, 계획은 docs/02-plan-scryfall-integration.md에, 회고는 docs/03-lessons-learned.md에 있습니다.

의존성

mcp        # the official MCP Python SDK
uvloop     # faster event loop (skipped on Windows)
httpx      # HTTP client for the Scryfall call

이 저장소에는 버전이 고정되어 있지 않습니다. 재현성이 필요한 경우 설치 시 버전을 고정하세요.

라이선스

MIT — Copyright (c) 2026 Jason Belk.

추가 읽기 자료

• 동반 게시물: Model Context Protocol 튜토리얼: 첫 번째 서버 구축하기

• 공식 MCP 문서: modelcontextprotocol.io

• Anthropic의 MCP 출시 발표: anthropic.com/news/model-context-protocol

• Scryfall API: scryfall.com/docs/api