startgg-mcp-server

start.gg GraphQL API 用の Model Context Protocol サーバーです。MCP クライアント（Claude Code、Claude Desktop など）が、自然言語で start.gg 上のあらゆるゲームのトーナメント、イベント、参加者、セット、順位、ストリームを検索・閲覧できるようにします。

これは何か？

start.gg は強力ですが複雑な GraphQL API を公開しています。entrant と participant と player の違い、整数のセット状態、複雑さに制限のあるページネーション、エポックタイムスタンプなど。このサーバーはその 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 エラーはリトライされません

• ツールごとに perPage を制限し、レスポンスが 1000 オブジェクトの複雑さ制限を超えないようにします（セットは高コスト: 各約 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 にあります（ドメインごとに 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