MTGDecks Metagame MCP

MTGDecks.net의 공개 페이지를 읽어 메타게임과 덱 정보를 일관된 JSON 형태로 정규화하는 Python/MCP PoC입니다.

문서화된 공개 API가 확인되지 않아 사이트의 공개 HTML과 URL 기반 필터를 사용합니다. 브라우저 로그인이나 쿠키는 필요하지 않습니다.

제공 기능

get_metagame(
    format: str,
    source: str = "all",
)

get_recent_decks(
    format: str,
    platform: str | None = None,
    game_type: str | None = None,
    max_pages: int = 3,
)

get_archetype_decks(
    format: str,
    archetype: str,
    limit: int = 20,
)

get_top_performing_decks(
    format: str,
    platform: str | None = None,
    min_players: int | None = None,
    limit: int = 20,
)

각 기능은 Python 함수와 MCP 도구로 모두 제공됩니다.

요구 사항

• Python 3.10 이상
• uv 권장

설치

git clone <repository-url>
cd Metagame-MCP
uv sync

개발 및 테스트 의존성까지 설치하려면 다음 명령을 사용합니다.

uv sync --extra dev

MCP 서버 실행

서버는 기본적으로 stdio 전송 방식으로 실행됩니다.

uv run mtgdecks-mcp

MCP 호스트 설정 예시는 다음과 같습니다. cwd는 이 저장소의 실제 절대 경로로 변경해야 합니다.

{
  "mcpServers": {
    "mtgdecks": {
      "command": "uv",
      "args": ["run", "mtgdecks-mcp"],
      "cwd": "C:\\path\\to\\Metagame-MCP"
    }
  }
}

등록되는 MCP 도구는 다음 네 개입니다.

• get_metagame
• get_recent_decks
• get_archetype_decks
• get_top_performing_decks

Python에서 사용

from mtgdecks_mcp import (
    get_archetype_decks,
    get_metagame,
    get_recent_decks,
    get_top_performing_decks,
)

metagame = get_metagame("Modern", source="mtgo")

recent = get_recent_decks(
    "Modern",
    platform="mtgo",
    game_type="BO3",
    max_pages=1,
)

archetype = get_archetype_decks(
    "Modern",
    "Boros Energy",
    limit=5,
)

top = get_top_performing_decks(
    "Modern",
    platform="mtgo",
    min_players=64,
    limit=10,
)

여러 번 조회할 때는 HTTP 연결을 재사용할 수 있도록 클라이언트를 직접 사용하는 편이 효율적입니다.

from mtgdecks_mcp import MTGDecksClient

with MTGDecksClient() as client:
    modern = client.get_metagame("Modern")
    pioneer = client.get_metagame("Pioneer")

인자

format

MTGDecks.net에서 사용하는 포맷 이름입니다. 예: Standard, Pioneer, Modern, Legacy, Pauper, Commander, Duel-Commander.

source

값	의미
all	전체 메타게임
mtgo	MTGO 이벤트 메타게임
major	최근 주요 이벤트 메타게임

mtgo-events, major-events, recent-major-events도 별칭으로 사용할 수 있습니다.

platform

• mtgo
• arena
• tabletop

대소문자는 구분하지 않습니다.

game_type

• BO1
• BO3

대소문자는 구분하지 않습니다.

조회 범위 제한

• max_pages: 1~10
• limit: 1~100
• min_players: 양의 정수

응답 구조

메타게임

{
  "format": "Modern",
  "source": "all",
  "url": "https://mtgdecks.net/Modern",
  "selected_deck_count": 10994,
  "updated_at": "2026-08-21 06:47:39",
  "archetypes": [
    {
      "name": "Boros Energy",
      "url": "https://mtgdecks.net/Modern/boros-energy",
      "meta_share_percent": 7.98,
      "trend_percent": -2.85,
      "tier": "A",
      "win_rate_percent": 49.0,
      "top_25_conversion": 0.95,
      "deck_count": 877,
      "price_usd": 1109.0
    }
  ]
}

덱 목록

덱 조회 기능은 공통적으로 pages와 decks를 반환합니다. pages에는 실제로 조회한 원본 페이지 URL이 들어갑니다.

{
  "format": "Modern",
  "pages": ["https://mtgdecks.net/Modern/decklists/page:1"],
  "decks": [
    {
      "name": "deck",
      "url": "https://mtgdecks.net/Modern/example-decklist-123",
      "author": "Player",
      "archetype": "Boros Energy",
      "game_type": "BO3",
      "platform": "mtgo",
      "event": "MTGO Modern Challenge",
      "event_level": 3,
      "players": 94,
      "spiciness_percent": 30.0,
      "date": "2026-08-20",
      "price_usd": 1112.0,
      "placement": "1st",
      "wins": 5,
      "losses": 0,
      "draws": 0,
      "win_rate_percent": 100.0
    }
  ]
}

MTGDecks 페이지에서 값을 제공하지 않는 필드는 null일 수 있습니다. 가격은 페이지의 Paper/TCGPlayer 기준 USD 값입니다.

get_top_performing_decks는 자체 성과 점수를 계산하지 않고 MTGDecks의 rank 오름차순 정렬을 사용합니다. 따라서 우승, 준우승, Top 8 등의 이벤트 성적이 좋은 덱부터 반환됩니다.

테스트

uv run pytest

테스트는 외부 사이트에 접속하지 않고 저장된 HTML 예시와 httpx.MockTransport를 사용합니다.

프로젝트 구조

src/mtgdecks_mcp/
├── __init__.py   # 공개 Python API
├── parsers.py    # MTGDecks HTML 정규화
├── server.py     # MCP 도구 등록과 stdio 서버
└── service.py    # URL 구성, HTTP 클라이언트, 네 가지 기능

tests/
├── test_parsers.py
└── test_service.py

제한 사항과 이용 조건

• 이 프로젝트는 공개 HTML 구조에 의존하므로 MTGDecks.net의 마크업이나 경로가 변경되면 파서 수정이 필요할 수 있습니다.
• 대량 크롤링, 병렬 수집, 캐시/데이터베이스 영속화는 PoC 범위에 포함하지 않았습니다.
• 원본 데이터의 정확성과 가용성은 MTGDecks.net에 의존합니다.
• 모든 정규화 결과에는 추적 가능한 원본 URL을 포함합니다.
• MTGDecks 이용약관은 콘텐츠를 개인·비상업적 용도로 제한합니다. 상업 서비스나 지속적인 대량 수집으로 확장하기 전에 MTGDecks 측의 허락 또는 API 파트너십을 확인하십시오.

관련 문서: MTGDecks 이용약관