Skip to main content
Glama
startgg-mcp-server

startgg-mcp-server

by tomo789

startgg-mcp-server

A Model Context Protocol server for the start.gg GraphQL API. It lets MCP clients (Claude Code, Claude Desktop, and others) discover tournaments, inspect events, entrants, sets, standings, and streams for any game on start.gg using natural language.

What is this?

start.gg exposes a powerful but complex GraphQL API: entrants vs participants vs players, integer set states, complexity-limited pagination, epoch timestamps. This server wraps that API in a small set of MCP tools with:

  • Normalized output — sets come back as { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } instead of raw GraphQL nesting

  • URL resolution — paste a start.gg URL, get tournament/event ids back

  • Built-in rate limiting, retries, and caching tuned to start.gg's documented limits

The server is game-agnostic. Game-specific logic (e.g. Smash upset detection) belongs in applications built on top — see examples/smash-ultimate-watcher.

Related MCP server: faceit-mcp

Features

  • 16 read-only tools covering discovery, tournaments, events, players, streams, and URL resolution

  • Input validation (Zod) on every tool — bad ids, oversized page sizes, and malformed URLs never reach the API

  • Sliding-window rate limiter (default 75 req/60s vs start.gg's 80), retries with exponential backoff, and Retry-After support

  • Short-TTL in-memory cache for metadata queries

  • Typed error codes: AUTH_ERROR, RATE_LIMITED, NOT_FOUND, INVALID_INPUT, STARTGG_GRAPHQL_ERROR, NETWORK_ERROR, INTERNAL_ERROR

  • GraphQL documents kept in graphql/ files, separate from code

  • The API token never appears in output, logs, or error messages

  • Compact JSON output (no pretty-printing) to keep tool results small

Requirements

  • Node.js >= 22

  • A start.gg API token

Getting a start.gg API token

  1. Log in to start.gg

  2. Open developer settings (Profile → Developer Settings)

  3. Create a personal access token and copy it

Treat the token like a password. This server reads it only from the STARTGG_TOKEN environment variable.

Installation

# run without installing
npx startgg-mcp-server

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

Requires STARTGG_TOKEN in the environment; MCP clients normally launch it for you (see the next section).

From source

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

MCP client setup

Claude Code (CLI)

claude mcp add startgg --env STARTGG_TOKEN=YOUR_TOKEN -- npx -y startgg-mcp-server

Running from a source checkout instead:

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

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "startgg": {
      "command": "npx",
      "args": ["-y", "startgg-mcp-server"],
      "env": {
        "STARTGG_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

From a source checkout, use "command": "node" and "args": ["/path/to/startgg-mcp-server/dist/cli.js"] instead.

Any MCP client that supports stdio servers works the same way: run node dist/cli.js (or the startgg-mcp-server bin once installed via npm) with STARTGG_TOKEN set.

Available tools

Discovery

Tool

Purpose

search_videogames

Find videogame ids by name (e.g. "Super Smash Bros. Ultimate" → 1386)

search_tournaments

General tournament search: name, videogame, country/state, date range, upcoming/past, open registration

get_upcoming_tournaments

Tournaments that haven't ended yet (includes in-progress), soonest first, with a days window

get_tournaments_by_videogame

Tournaments for one videogame id (upcoming / past / all)

Tournament

Tool

Purpose

get_tournament

Details, schedule, venue, events list, configured streams

get_tournament_events

Events (brackets) of a tournament, optionally filtered by videogame

get_tournament_entrants

Tournament-level participants (attendees); per-event seeding lives in get_event_entrants

get_stream_queue

Stream queue: streams (with derived Twitch URLs) and the sets assigned to each

Event

Tool

Purpose

get_event

Event details including phases (Pools, Top 8, ...) with phase ids

get_event_entrants

Entrants with seed, players, DQ flag; pagination or fetchAll

get_event_standings

Placements (use perPage: 8 for Top 8)

get_event_sets

Normalized sets with stream; filter by state, phase, round, entrants, players, VOD; includeGames for per-game details

get_set_games

Per-game stage / winner / character picks for one set; see coverage note

Player

Tool

Purpose

get_player

Player by id: gamer tag, prefix, linked user

get_player_sets

A player's recent sets across tournaments

Utility

Tool

Purpose

resolve_startgg_url

start.gg URL/slug → { type, tournamentId, eventId, slugs, names }

Tournament/event tools accept either a numeric id, a slug, or a full start.gg URL. Scheme-less URLs (start.gg/tournament/...) and <t>/event/<e> slugs are accepted too — you rarely need resolve_startgg_url explicitly, but it is there when you want the ids.

Normalized set shape

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

Notes grounded in the live API:

  • roundNumber < 0 means losers bracket; round is the human-readable name

  • a score of -1 is start.gg's disqualification marker

  • unstarted "preview" sets have string ids like "preview_3430499_2_0"

  • state names are decoded from the integer stateRaw; both are always returned

  • entrant1/entrant2 use a players array, so doubles/teams work unchanged

Games and characters

get_set_games (and get_event_sets with includeGames: true) add per-game details when start.gg has them:

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

derivedCharacters summarizes unique character names per entrant in first-appearance order across games. This is derived, not an API field.

Character and stage data only exists when the set was reported with it. In a 2026-09 sample, late rounds (Top 8 / streamed) had it on about 90% of completed sets; early pools about 5%. An empty games array means not reported, not that no games were played. Typical flow: get_event_sets (e.g. phaseIds for Top 8) → pick set ids → get_set_games. For many sets at once, get_event_sets with includeGames: true.

Examples

Things to ask an MCP client once connected:

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?

A standalone example application (videogame lookup → upcoming tournaments → sets → upset candidates by seed difference) lives in examples/smash-ultimate-watcher.

Environment variables

Variable

Required

Default

Purpose

STARTGG_TOKEN

yes

—

start.gg API token

STARTGG_ENABLE_WRITES

no

false

Reserved. No write tools exist yet; the flag only logs a notice

STARTGG_RATE_LIMIT

no

75

Requests per 60s window (hard-capped at 80)

STARTGG_TIMEOUT_MS

no

30000

Per-request HTTP timeout

STARTGG_CACHE

no

on

Set off to disable the in-memory cache

The API endpoint is deliberately not configurable through the environment: the token is only ever sent to api.start.gg. When using the client as a library (tests, tooling), inject apiUrl/fetchFn via the StartggClient constructor.

Out-of-range or non-numeric values for STARTGG_RATE_LIMIT / STARTGG_TIMEOUT_MS fall back to the default and log a warning on stderr.

Without STARTGG_TOKEN the server still starts and lists tools, but every call returns a clear AUTH_ERROR explaining how to fix it.

Security

  • The token is read from the environment only, sent only to api.start.gg, and never included in tool output, logs, or error messages

  • All tools are read-only; no mutations are implemented

  • .env files are git-ignored; use .env.example as a template

  • User-supplied input is schema-validated before any request is built

Rate limits

start.gg allows 80 requests per 60 seconds and at most 1000 objects per request. This server:

  • keeps a sliding-window budget below the request limit (default 75/60s)

  • retries 429 (honoring Retry-After) and transient 5xx errors with exponential backoff, at most 3 retries — GraphQL errors are never retried

  • caps perPage per tool so responses stay under the 1000-object complexity limit (sets are expensive: ~26+ objects each, hence perPage <= 30)

  • caps fetchAll at 5 pages per tool (output is meant for an LLM context, so it stays around 100 KB of compact JSON) and reports truncated: true when it stops early

Development

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 documents live in graphql/*.graphql (one file per domain, multiple named operations per file; requests select an operation via operationName). Schema facts verified against the live API are recorded in docs/startgg-api-notes.md — read it before adding fields.

Testing

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 cover the URL resolver, normalizers, input validation, pagination, GraphQL/HTTP error handling, the rate limiter, and the cache.

License

MIT

Available Tools

15 tools
get_eventGet eventA
Read-only

Get one event (bracket) of a tournament: name, start time, state, entrant count, videogame, parent tournament, and its phases (e.g. Pools, Top 8) with phase ids you can pass to get_event_sets phaseIds.

Inputs: url, slug, eventId.

get_event_entrantsGet event entrantsB
Read-only

List an event's entrants with their seed (initialSeedNum), players (gamer tags), and disqualification flag. Supports pagination or fetchAll.

Inputs: url, name, page, slug, +3 more.

get_event_setsGet event setsA
Read-only

List an event's sets (matches) in a normalized form: round, state (COMPLETED/ACTIVE/...), both entrants with seeds and players, per-entrant score (-1 = DQ), winner, phase, and VOD URL when available. Filter by state, phaseIds (from get_event's phases, e.g. Top 8), round, or entrants.

Inputs: url, page, slug, state, +9 more.

get_event_standingsGet event standingsA
Read-only

Get an event's standings (final or current placements), best first. Includes each entrant's seed so upsets are visible. Use perPage 8 for Top 8.

Inputs: url, page, slug, eventId, +2 more.

get_playerGet playerA
Read-only

Get a start.gg player by numeric player id: gamer tag, team prefix, and linked user. Player ids appear in set/entrant results (players[].playerId).

Inputs: playerId (required).

get_player_setsGet player setsA
Read-only

Get a player's recent sets across tournaments (most recent first), in the same normalized set form as get_event_sets, plus the event and tournament each set belongs to. Filter by set state (e.g. COMPLETED).

Inputs: playerId (required), page, state, perPage.

get_stream_queueGet stream queueA
Read-only

Get a tournament's stream queue: each stream (source, channel name, derived URL for Twitch) with the sets currently assigned to it. Returns empty queues when nothing is queued. For the list of configured streams regardless of queue, use get_tournament.

Inputs: url, slug, tournamentId.

get_tournamentGet tournamentA
Read-only

Get one tournament's details: schedule, venue/location, registration, its events (with videogame and entrant counts), and its configured streams. Identify the tournament by numeric id, slug, or start.gg URL.

Inputs: url, slug, tournamentId.

get_tournament_entrantsGet tournament participantsA
Read-only

List a tournament's registered participants (attendees) with gamer tags. Note: these are tournament-level registrations; for per-event entrants with seeding, use get_event_entrants instead.

Inputs: url, page, slug, perPage, +2 more.

get_tournament_eventsGet tournament eventsA
Read-only

List the events (brackets) of a tournament, optionally filtered to one videogame id. Use the returned event id or slug with get_event_entrants / get_event_sets / get_event_standings.

Inputs: url, slug, videogameId, tournamentId.

get_tournaments_by_videogameGet tournaments by videogameA
Read-only

List tournaments for a specific videogame id. timeframe selects upcoming (default), past, or all; combine with afterDate/beforeDate and location filters as needed.

Inputs: videogameId (required), page, perPage, addrState, +4 more.

get_upcoming_tournamentsGet upcoming tournamentsA
Read-only

List tournaments that have not ended yet (including ones in progress), soonest first. Filter by videogame id (get it from search_videogames), country/state, and a time window in days.

Inputs: page, perPage, addrState, withinDays, +3 more.

resolve_startgg_urlResolve start.gg URLA
Read-only

Turn a start.gg tournament or event URL (or slug) into internal ids and slugs. Example: "https://www.start.gg/tournament/genesis-9/event/ultimate-singles" -> { type: event, tournamentId, eventId, ... }. Use this first when the user pastes a start.gg link, then call the other tools with the returned ids.

Inputs: url (required).

search_tournamentsSearch tournamentsA
Read-only

Search start.gg tournaments with flexible filters: name, videogame ids, country/state, date range (afterDate/beforeDate on start time), upcoming/past, open registration.

Inputs: name, page, past, sortBy, +9 more.

search_videogamesSearch videogamesA
Read-only

Search start.gg's videogame catalog by name and get videogame ids. Use this first to find the id for a game (e.g. "Super Smash Bros. Ultimate" -> 1386), then pass that id to tournament discovery tools.

Inputs: name (required), page, perPage.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear differentiators even among similar tools (e.g., search_tournaments vs. get_upcoming_tournaments). Descriptions explicitly note when to use each, such as tournament-level vs. event-level entrants, preventing confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (search_, get_, resolve_). The verbs are simple and uniform, making the set highly predictable and easy to navigate.

    Tool Count5/5

    With 15 tools, the server is well-scoped for the start.gg domain, covering search, tournament details, events, players, streams, and URL resolution. Each tool has a clear purpose, and the count is within the ideal range for coherence without bloat.

    Completeness5/5

    The tool set provides comprehensive read-only coverage of the start.gg platform, including videogame search, tournament discovery, detailed tournament and event queries, entrant/standings/set retrieval, player history, stream queues, and URL resolution. No obvious gaps for the apparent use case.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides access to the Start.gg GraphQL API for querying tournament information, event standings, and player statistics. It also enables bracket management tasks like retrieving match sets and reporting winners through natural language.
      1
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query the FACEIT platform for players, matches, hubs, and tournaments through typed MCP tools generated from the FACEIT Data API v4.
      64
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query Riot Games data such as accounts, summoners, match history, and champion mastery via natural language.
      126 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables querying Chess.com player profiles, ratings, game histories, and leaderboard rankings through a natural language MCP interface.
      95 npm
      MIT