start.gg MCP Server

startgg-mcp-server

start.gg GraphQL API 用の Model Context Protocol サーバーです。MCP クライアント（Claude Code、 Claude Desktop など）から、自然言語を使って start.gg 上のあらゆるゲーム のトーナメント、イベント、参加者、 セット、順位表、配信を見つけて調べられます。

これは何ですか？

start.gg は強力ですが、複雑な GraphQL API を提供しています。参加者とプレイヤーの違い、整数で表されるセットの状態、複雑さによって制限されるページネーション、エポックタイムスタンプなどです。このサーバーは、次の機能を備えた少数の MCP ツールで API をラップします。

• 正規化された出力 — セットは、GraphQL の生のネスト構造ではなく、{ round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } として返されます
• URL 解決 — start.gg の URL を貼り付けると、トーナメント ID とイベント ID が返されます
• start.gg が公開している制限に合わせた、組み込みのレート制限、再試行、キャッシュ

このサーバーはゲームに依存しません。ゲーム固有のロジック（例：Smash の番狂わせ検出）は、このサーバーを基盤とするアプリケーション側に実装してください。詳しくは examples/smash-ultimate-watcher を参照してください。

機能

• 検索、トーナメント、イベント、プレイヤー、配信、URL 解決をカバーする、読み取り専用の 16 個のツール
• すべてのツールで入力を検証（Zod）— 不正な ID、過大なページサイズ、形式が不正な URL が API に到達することはありません
• スライディングウィンドウ方式のレートリミッター（デフォルトは start.gg の上限 80 に対して 75 リクエスト／60 秒）、指数バックオフによる再試行、Retry-After への対応
• メタデータクエリ向けの短い TTL を設定したインメモリキャッシュ
• 型付きエラーコード：AUTH_ERROR、RATE_LIMITED、NOT_FOUND、INVALID_INPUT、STARTGG_GRAPHQL_ERROR、NETWORK_ERROR、INTERNAL_ERROR
• GraphQL ドキュメントはコードと分けて graphql/ ファイルに保存
• API トークンは出力、ログ、エラーメッセージに表示されません
• ツールの結果を小さく保つため、コンパクトな JSON 出力（整形なし）

必要条件

• Node.js >= 22
• start.gg API トークン

start.gg API トークンの取得

1. start.gg にログインします
2. 開発者設定 を開きます（プロフィール → 開発者設定）
3. 個人用アクセストークンを作成してコピーします

トークンはパスワードと同様に取り扱ってください。このサーバーは STARTGG_TOKEN 環境変数からのみトークンを読み取ります。

インストール

npm から（推奨）

# run without installing
npx startgg-mcp-server

# or install globally
npm install -g startgg-mcp-server

環境変数に STARTGG_TOKEN が必要です。通常は MCP クライアントが起動時に設定します（次のセクションを参照してください）。

ソースから

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 -- npx -y startgg-mcp-server

ソースをチェックアウトして実行する場合：

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": "npx",
      "args": ["-y", "startgg-mcp-server"],
      "env": {
        "STARTGG_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

ソースをチェックアウトしている場合は、代わりに "command": "node" と "args": ["/path/to/startgg-mcp-server/dist/cli.js"] を使用してください。

stdio サーバーをサポートする MCP クライアントであれば、同じ方法で利用できます。STARTGG_TOKEN を設定して、node dist/cli.js（または npm 経由でインストールした場合は startgg-mcp-server バイナリ）を実行します。

利用可能なツール

検索

ツール	目的
search_videogames	名前からビデオゲーム ID を検索します（例：「Super Smash Bros. Ultimate」→ 1386）
search_tournaments	トーナメント全般を検索します：名前、ビデオゲーム、国／州、開催期間、開催予定／過去、参加登録受付中
get_upcoming_tournaments	終了していない（進行中のものを含む）トーナメントを、開催日時が近い順に、日数の範囲を指定して取得します
get_tournaments_by_videogame	1 つのビデオゲーム ID に対応するトーナメントを取得します（開催予定／過去／すべて）

トーナメント

ツール	用途
get_tournament	詳細、スケジュール、会場、イベント一覧、設定済みストリーム
get_tournament_events	トーナメントのイベント（ブラケット）。必要に応じてビデオゲームで絞り込み可能
get_tournament_entrants	トーナメント単位の参加者（出場者）。イベントごとのシード順位は get_event_entrants で取得
get_stream_queue	ストリームキュー：ストリーム（導出された Twitch URL を含む）と、それぞれに割り当てられたセット

イベント

ツール	用途
get_event	フェーズ（プール、トップ 8 など）とフェーズ ID を含むイベントの詳細
get_event_entrants	シード順位、プレイヤー、DQ フラグを含む参加者。ページネーションまたは fetchAll に対応
get_event_standings	順位（トップ 8 の場合は perPage: 8 を使用）
get_event_sets	stream を含む正規化されたセット。状態、フェーズ、ラウンド、参加者、プレイヤー、VOD で絞り込み可能。ゲームごとの詳細には includeGames を使用
get_set_games	1 つのセットにおけるゲームごとのステージ／勝者／キャラクター選択。対応状況については注記を参照

プレイヤー

ツール	用途
get_player	ID によるプレイヤー情報：ゲーマータグ、プレフィックス、リンクされたユーザー
get_player_sets	トーナメントを横断した、プレイヤーの最近のセット

ユーティリティ

ツール	用途
resolve_startgg_url	start.gg の URL／スラッグ → { type, tournamentId, eventId, slugs, names }

トーナメント／イベントの各ツールでは、数値 ID、スラッグ、完全な start.gg URL のいずれかを指定できます。スキームを省略した URL（start.gg/tournament/...）と <t>/event/<e> 形式のスラッグも使用できます。通常、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 配列を使うため、ダブルス／チームでもそのまま機能します

ゲームとキャラクター

get_set_games（および includeGames: true を指定した get_event_sets）では、start.gg に情報がある場合にゲームごとの 詳細が追加されます。

{
  "orderNum": 1,
  "winnerEntrantId": 24480092,
  "stage": { "id": 484, "name": "Small Battlefield" },
  "selections": [{ "entrantId": 24481002, "character": { "id": 1846, "name": "Kazuya" } }]
}

derivedCharacters は、各参加者のユニークなキャラクター名を、ゲーム内での初出順にまとめたものです。 これは導出された値であり、API のフィールドではありません。

キャラクターとステージのデータは、その情報とともにセットが報告された場合にのみ存在します。2026-09 のサンプルでは、終盤のラウンド（トップ 8／配信あり）で、完了したセットの約 90% にデータがありました。序盤のプールでは約 5% でした。games 配列が空でも、ゲームが行われなかったという意味ではなく、報告されていないことを示します。一般的な流れ：get_event_sets（例：トップ 8 の phaseIds）→ セット ID を選択 → get_set_games。複数のセットをまとめて取得する場合は、includeGames: true を指定した get_event_sets を使用します。

例

接続後に 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 にあります。

環境変数

変数	必須	デフォルト	用途
STARTGG_TOKEN	はい	—	start.gg API トークン
STARTGG_ENABLE_WRITES	いいえ	false	予約済み。書き込みツールはまだありません。このフラグは通知をログに記録するだけです
STARTGG_RATE_LIMIT	いいえ	75	60 秒間のリクエスト数（上限は 80）
STARTGG_TIMEOUT_MS	いいえ	30000	リクエストごとの HTTP タイムアウト
STARTGG_CACHE	いいえ	on	メモリ内キャッシュを無効にするには off を設定します

API エンドポイントは意図的に環境変数から設定できないようにしています。トークンが送信されるのは api.start.gg のみです。クライアントをライブラリとして使用する場合（テスト、ツールなど）は、StartggClient コンストラクターに apiUrl／fetchFn を渡してください。

STARTGG_RATE_LIMIT／STARTGG_TIMEOUT_MS に範囲外の値または数値以外の値を指定すると、デフォルト値が使われ、標準エラー出力に警告が記録されます。

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 の上限を設けています（セットは 1 件あたり約 26 個以上のオブジェクトを消費するため、perPage <= 30）
• ツールごとに fetchAll を最大 5 ページに制限します（出力は LLM のコンテキスト向けで、コンパクトな JSON で約 100 KB に収まるため）。途中で停止した場合は 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 にあります（ドメインごとに 1 ファイルで、各ファイルには名前付きオペレーションが複数含まれます。リクエストでは 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