startgg-mcp-server

start.gg GraphQL API용 Model Context Protocol 서버입니다. MCP 클라이언트(Claude Code, Claude Desktop 등)가 자연어를 사용하여 start.gg의 모든 게임에 대한 토너먼트, 이벤트, 참가자, 세트, 순위, 스트림을 조회할 수 있게 해줍니다.

이게 무엇인가요?

start.gg는 강력하지만 복잡한 GraphQL API를 제공합니다: entrant vs participant vs player, 정수 세트 상태, 복잡도 제한이 있는 페이지네이션, epoch 타임스탬프 등이 그것입니다. 이 서버는 해당 API를 소수의 MCP 도구로 감싸며 다음과 같은 특징을 제공합니다:

• 정규화된 출력 — 세트가 원시 GraphQL 중첩 구조 대신 { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } 형태로 반환됩니다

• URL 해석 — start.gg URL을 붙여넣으면 토너먼트/이벤트 id를 돌려받습니다

• start.gg의 문서화된 한도에 맞춰 조정된 내장 속도 제한, 재시도, 캐싱

이 서버는 게임에 종속되지 않습니다. 게임별 로직(예: Smash 업셋 감지)은 그 위에 구축되는 애플리케이션에 속합니다 — examples/smash-ultimate-watcher를 참조하세요.

Related MCP server: Start.gg MCP Server

기능

• 탐색, 토너먼트, 이벤트, 플레이어, 스트림, URL 해석을 다루는 15개의 읽기 전용 도구

• 모든 도구에 대한 입력 검증(Zod) — 잘못된 id, 과도한 페이지 크기, 잘못된 형식의 URL은 API에 도달하지 않습니다

• 슬라이딩 윈도우 속도 제한기(기본 75회/60초, start.gg의 80회 대비), 지수 백오프 재시도, Retry-After 지원

• 메타데이터 쿼리를 위한 짧은 TTL 인메모리 캐시

• 타입화된 오류 코드: AUTH_ERROR, RATE_LIMITED, NOT_FOUND, INVALID_INPUT, STARTGG_GRAPHQL_ERROR, NETWORK_ERROR, INTERNAL_ERROR

• GraphQL 문서는 코드와 분리되어 graphql/ 파일에 보관

• API 토큰은 출력, 로그, 오류 메시지에 절대 나타나지 않습니다

요구 사항

• Node.js >= 20

• start.gg API 토큰

start.gg API 토큰 받기

1. start.gg에 로그인합니다

2. **개발자 설정**을 엽니다 (프로필 → 개발자 설정)

3. 개인 액세스 토큰을 생성하고 복사합니다

토큰을 비밀번호처럼 취급하세요. 이 서버는 STARTGG_TOKEN 환경 변수에서만 토큰을 읽습니다.

설치

git clone https://github.com/tomo789/startgg-mcp-server.git
cd startgg-mcp-server
npm install
npm run build

MCP 클라이언트 설정

Claude Code (CLI)

claude mcp add startgg --env STARTGG_TOKEN=YOUR_TOKEN -- node /path/to/startgg-mcp-server/dist/cli.js

Claude Desktop

claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "startgg": {
      "command": "node",
      "args": ["/path/to/startgg-mcp-server/dist/cli.js"],
      "env": {
        "STARTGG_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

stdio 서버를 지원하는 모든 MCP 클라이언트는 동일한 방식으로 작동합니다: STARTGG_TOKEN을 설정한 상태에서 node dist/cli.js(또는 npm으로 설치한 경우 startgg-mcp-server 바이너리)를 실행하면 됩니다.

사용 가능한 도구

탐색

토너먼트

이벤트

플레이어

유틸리티

토너먼트/이벤트 도구는 숫자 id, 슬러그, 또는 전체 start.gg URL 중 하나를 허용합니다 — resolve_startgg_url을 명시적으로 호출할 필요는 거의 없지만, id가 필요할 때 사용할 수 있습니다.

정규화된 세트 구조

{
  "id": 106877974,
  "round": "Grand Final",
  "roundNumber": 3,
  "state": "COMPLETED",
  "stateRaw": 3,
  "completedAt": "2026-08-24T07:19:34.000Z",
  "entrant1": {
    "entrantId": 24480092,
    "name": "LittleMacMain",
    "seed": 5,
    "players": [{ "playerId": 3655189, "gamerTag": "LittleMacMain", "prefix": "" }],
    "score": 2
  },
  "entrant2": { "...": "same shape" },
  "score": { "entrant1": 2, "entrant2": 3, "displayScore": "LittleMacMain 2 - RenSuø 3" },
  "winnerEntrantId": 24481002,
  "phase": { "id": 1994001, "name": "Bracket" },
  "vodUrl": null
}

실제 API에 근거한 참고 사항:

• roundNumber < 0은 패자 브래킷을 의미하며, round는 사람이 읽을 수 있는 이름입니다

• 점수 -1은 start.gg의 실격 표시입니다

• 시작되지 않은 "미리보기" 세트는 "preview_3430499_2_0" 같은 문자열 id를 가집니다

• state 이름은 정수 stateRaw에서 디코딩되며, 둘 다 항상 반환됩니다

• entrant1/entrant2는 players 배열을 사용하므로 더블스/팀도 변경 없이 작동합니다

예시

연결 후 MCP 클라이언트에 물어볼 수 있는 것들:

Find upcoming Super Smash Bros. Ultimate tournaments this week.

Get the entrants and seeds for this start.gg tournament URL:
https://www.start.gg/tournament/.../event/...

Show me completed sets from Top 8 of that event.

Which streams are assigned to sets at this tournament?

What were the biggest seed upsets in this event?

독립 실행형 예제 애플리케이션(비디오게임 조회 → 예정 토너먼트 → 세트 → 시드 차이 기반 업셋 후보)은 examples/smash-ultimate-watcher에 있습니다.

환경 변수

API 엔드포인트는 의도적으로 환경을 통해 구성할 수 없습니다: 토큰은 api.start.gg로만 전송됩니다. 클라이언트를 라이브러리로 사용할 때(테스트, 도구)는 StartggClient 생성자를 통해 apiUrl/fetchFn을 주입하세요.

STARTGG_TOKEN이 없어도 서버는 시작되고 도구를 나열하지만, 모든 호출은 해결 방법을 설명하는 명확한 AUTH_ERROR를 반환합니다.

보안

• 토큰은 환경에서만 읽히며, api.start.gg로만 전송되고, 도구 출력, 로그, 오류 메시지에 절대 포함되지 않습니다

• 모든 도구는 읽기 전용이며, 변경 작업은 구현되어 있지 않습니다

• .env 파일은 git에서 제외됩니다. .env.example을 템플릿으로 사용하세요

• 사용자 입력은 요청이 구성되기 전에 스키마 검증됩니다

속도 제한

start.gg는 60초당 80회 요청과 요청당 최대 1000개 객체를 허용합니다. 이 서버는:

• 요청 한도 아래로 슬라이딩 윈도우 예산을 유지합니다 (기본 75/60초)

• 429(Retry-After 준수) 및 일시적인 5xx 오류를 지수 백오프로 최대 3회 재시도합니다 — GraphQL 오류는 절대 재시도하지 않습니다

• 응답이 1000개 객체 복잡도 한도 아래에 머물도록 도구별로 perPage를 제한합니다 (세트는 비용이 높습니다: 각각 ~26+ 객체, 따라서 perPage <= 30)

• fetchAll을 고정 페이지 예산으로 제한하고 조기 중단 시 truncated: true를 보고합니다

개발

npm run dev        # run from source (tsx)
npm run build      # compile to dist/
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run format     # prettier

GraphQL 문서는 graphql/*.graphql에 있습니다 (도메인당 하나의 파일, 파일당 여러 명명된 작업; 요청은 operationName으로 작업을 선택합니다). 실제 API에 대해 검증된 스키마 사실은 docs/startgg-api-notes.md에 기록되어 있습니다 — 필드를 추가하기 전에 읽어보세요.

테스트

npm test                    # unit tests (fixtures/mocks only, no network)
STARTGG_INTEGRATION=1 STARTGG_TOKEN=... npm test   # + 2 live API smoke tests
STARTGG_TOKEN=... node scripts/smoke.mjs           # full stdio end-to-end smoke (~10 live requests)

단위 테스트는 URL 해석기, 정규화기, 입력 검증, 페이지네이션, GraphQL/HTTP 오류 처리, 속도 제한기, 캐시를 다룹니다.

라이선스

MIT