startgg-mcp-server

Ein Model Context Protocol-Server für die start.gg GraphQL-API. Er ermöglicht es MCP-Clients (Claude Code, Claude Desktop und anderen), Turniere zu entdecken, Events, Teilnehmer, Sets, Platzierungen und Streams für jedes Spiel auf start.gg in natürlicher Sprache zu durchsuchen.

Was ist das?

start.gg bietet eine leistungsstarke, aber komplexe GraphQL-API: Entrants vs. Teilnehmer vs. Spieler, ganzzahlige Set-Zustände, komplexitätsbegrenzte Paginierung, Epochen-Zeitstempel. Dieser Server kapselt diese API in eine kleine Reihe von MCP-Tools mit:

• Normalisierte Ausgabe — Sets kommen als { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } zurück, statt als rohe GraphQL-Verschachtelung

• URL-Auflösung — füge eine start.gg-URL ein, erhalte Turnier-/Event-IDs zurück

• Integrierte Ratenbegrenzung, Wiederholungen und Caching abgestimmt auf die dokumentierten Grenzen von start.gg

Der Server ist spielunabhängig. Spielspezifische Logik (z. B. Smash-Upset-Erkennung) gehört in Anwendungen, die darauf aufbauen — siehe examples/smash-ultimate-watcher.

Related MCP server: Start.gg MCP Server

Funktionen

• 15 schreibgeschützte Tools für Entdeckung, Turniere, Events, Spieler, Streams und URL-Auflösung

• Eingabevalidierung (Zod) bei jedem Tool — ungültige IDs, übermäßige Seitengrößen und fehlerhafte URLs erreichen nie die API

• Gleitendes Fenster-Ratenlimit (Standard 75 Anfragen/60s gegenüber 80 bei start.gg), Wiederholungen mit exponentiellem Backoff und Retry-After-Unterstützung

• In-Memory-Cache mit kurzer TTL für Metadatenabfragen

• Typisierte Fehlercodes: AUTH_ERROR, RATE_LIMITED, NOT_FOUND, INVALID_INPUT, STARTGG_GRAPHQL_ERROR, NETWORK_ERROR, INTERNAL_ERROR

• GraphQL-Dokumente in graphql/-Dateien, getrennt vom Code

• Das API-Token erscheint nie in Ausgabe, Logs oder Fehlermeldungen

Voraussetzungen

• Node.js >= 20

• Ein start.gg-API-Token

So erhalten Sie ein start.gg-API-Token

1. Melden Sie sich bei start.gg an

2. Öffnen Sie die Entwicklereinstellungen (Profil → Entwicklereinstellungen)

3. Erstellen Sie ein persönliches Zugriffstoken und kopieren Sie es

Behandeln Sie das Token wie ein Passwort. Dieser Server liest es nur aus der Umgebungsvariable STARTGG_TOKEN.

Installation

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

MCP-Client-Einrichtung

Claude Code (CLI)

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

Claude Desktop

Fügen Sie zu claude_desktop_config.json hinzu:

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

Jeder MCP-Client, der stdio-Server unterstützt, funktioniert auf die gleiche Weise: Führen Sie node dist/cli.js (oder das startgg-mcp-server-Binärprogramm, sobald es über npm installiert ist) mit gesetzter STARTGG_TOKEN aus.

Verfügbare Tools

Entdeckung

Turnier

Event

Spieler

Dienstprogramm

Turnier-/Event-Tools akzeptieren entweder eine numerische ID, einen Slug oder eine vollständige start.gg-URL — Sie benötigen resolve_startgg_url selten explizit, aber es ist da, wenn Sie die IDs möchten.

Normalisierte Set-Struktur

{
  "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
}

Hinweise, die auf der Live-API basieren:

• roundNumber < 0 bedeutet Verlierer-Bracket; round ist der menschenlesbare Name

• ein Ergebnis von -1 ist start.ggs Disqualifikationsmarker

• nicht gestartete „Preview“-Sets haben String-IDs wie "preview_3430499_2_0"

• state-Namen werden aus dem ganzzahligen stateRaw dekodiert; beide werden immer zurückgegeben

• entrant1/entrant2 verwenden ein players-Array, sodass Doppel/Teams unverändert funktionieren

Beispiele

Dinge, die Sie einen MCP-Client fragen können, sobald er verbunden ist:

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?

Eine eigenständige Beispielanwendung (Videospiel-Suche → anstehende Turniere → Sets → Upset-Kandidaten nach Setzplatz-Differenz) befindet sich in examples/smash-ultimate-watcher.

Umgebungsvariablen

Der API-Endpunkt ist bewusst nicht über die Umgebung konfigurierbar: Das Token wird nur an api.start.gg gesendet. Wenn Sie den Client als Bibliothek verwenden (Tests, Tooling), injizieren Sie apiUrl/fetchFn über den StartggClient-Konstruktor.

Ohne STARTGG_TOKEN startet der Server weiterhin und listet Tools auf, aber jeder Aufruf gibt einen klaren AUTH_ERROR zurück, der erklärt, wie man ihn behebt.

Sicherheit

• Das Token wird nur aus der Umgebung gelesen, nur an api.start.gg gesendet und nie in Tool-Ausgaben, Logs oder Fehlermeldungen aufgenommen

• Alle Tools sind schreibgeschützt; es sind keine Mutationen implementiert

• .env-Dateien sind git-ignoriert; verwenden Sie .env.example als Vorlage

• Benutzereingaben werden vor dem Erstellen einer Anfrage schemavalidisiert

Ratenbegrenzungen

start.gg erlaubt 80 Anfragen pro 60 Sekunden und höchstens 1000 Objekte pro Anfrage. Dieser Server:

• hält ein gleitendes Fensterbudget unter dem Anfragelimit (Standard 75/60s)

• wiederholt 429 (unter Beachtung von Retry-After) und vorübergehende 5xx-Fehler mit exponentiellem Backoff, höchstens 3 Wiederholungen — GraphQL-Fehler werden nie wiederholt

• begrenzt perPage pro Tool, sodass Antworten unter dem 1000-Objekt-Komplexitätslimit bleiben (Sets sind teuer: ~26+ Objekte pro Set, daher perPage <= 30)

• begrenzt fetchAll auf ein festes Seitenbudget und meldet truncated: true, wenn es vorzeitig stoppt

Entwicklung

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-Dokumente befinden sich in graphql/*.graphql (eine Datei pro Domäne, mehrere benannte Operationen pro Datei; Anfragen wählen eine Operation über operationName aus). Schema-Fakten, die gegen die Live-API verifiziert wurden, sind in docs/startgg-api-notes.md festgehalten — lesen Sie diese, bevor Sie Felder hinzufügen.

Tests

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)

Unit-Tests decken den URL-Resolver, Normalisierer, Eingabevalidierung, Paginierung, GraphQL/HTTP-Fehlerbehandlung, den Ratenbegrenzer und den Cache ab.

Lizenz

MIT