startgg-mcp-server
Provides a natural-language MCP interface to start.gg's GraphQL API for discovering tournaments and inspecting events, entrants, sets, standings, streams, and players (read-only).
Search the start.gg videogame catalog to get game ids (e.g. Smash Ultimate → 1386).
Find tournaments by name, videogame, country/state, date range, upcoming/past, or open registration.
Get tournament details: schedule, venue, events, registered participants, and configured streams.
Get an event's phases, entrants with seeds/players/DQ flags, and standings (e.g. Top 8).
List sets in a normalized form with round, state, scores, winner, phase, and VOD URL; filter by state, phase, round, entrants, or VOD presence.
Look up individual players and their recent sets across tournaments.
Resolve start.gg tournament/event URLs or slugs into ids and slugs for use with other tools.
All tools are read-only, input-validated, rate-limited, and return normalized output instead of raw GraphQL nesting.
Provides tools for interacting with start.gg's GraphQL API, enabling discovery of tournaments, events, entrants, sets, standings, and streams for any game on start.gg.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@startgg-mcp-server Find upcoming Super Smash Bros. Ultimate tournaments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 nestingURL 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-AftersupportShort-TTL in-memory cache for metadata queries
Typed error codes:
AUTH_ERROR,RATE_LIMITED,NOT_FOUND,INVALID_INPUT,STARTGG_GRAPHQL_ERROR,NETWORK_ERROR,INTERNAL_ERRORGraphQL documents kept in
graphql/files, separate from codeThe 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
Log in to start.gg
Open developer settings (Profile → Developer Settings)
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
From npm (recommended)
# run without installing
npx startgg-mcp-server
# or install globally
npm install -g startgg-mcp-serverRequires 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 buildMCP client setup
Claude Code (CLI)
claude mcp add startgg --env STARTGG_TOKEN=YOUR_TOKEN -- npx -y startgg-mcp-serverRunning from a source checkout instead:
claude mcp add startgg --env STARTGG_TOKEN=YOUR_TOKEN -- node /path/to/startgg-mcp-server/dist/cli.jsClaude 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 |
| Find videogame ids by name (e.g. "Super Smash Bros. Ultimate" → 1386) |
| General tournament search: name, videogame, country/state, date range, upcoming/past, open registration |
| Tournaments that haven't ended yet (includes in-progress), soonest first, with a days window |
| Tournaments for one videogame id (upcoming / past / all) |
Tournament
Tool | Purpose |
| Details, schedule, venue, events list, configured streams |
| Events (brackets) of a tournament, optionally filtered by videogame |
| Tournament-level participants (attendees); per-event seeding lives in |
| Stream queue: streams (with derived Twitch URLs) and the sets assigned to each |
Event
Tool | Purpose |
| Event details including phases (Pools, Top 8, ...) with phase ids |
| Entrants with seed, players, DQ flag; pagination or |
| Placements (use |
| Normalized sets with |
| Per-game stage / winner / character picks for one set; see coverage note |
Player
Tool | Purpose |
| Player by id: gamer tag, prefix, linked user |
| A player's recent sets across tournaments |
Utility
Tool | Purpose |
| start.gg URL/slug → |
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 < 0means losers bracket;roundis the human-readable namea score of
-1is start.gg's disqualification markerunstarted "preview" sets have string ids like
"preview_3430499_2_0"statenames are decoded from the integerstateRaw; both are always returnedentrant1/entrant2use aplayersarray, 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 |
| yes | — | start.gg API token |
| no |
| Reserved. No write tools exist yet; the flag only logs a notice |
| no |
| Requests per 60s window (hard-capped at 80) |
| no |
| Per-request HTTP timeout |
| no |
| Set |
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 messagesAll tools are read-only; no mutations are implemented
.envfiles are git-ignored; use.env.exampleas a templateUser-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(honoringRetry-After) and transient 5xx errors with exponential backoff, at most 3 retries — GraphQL errors are never retriedcaps
perPageper tool so responses stay under the 1000-object complexity limit (sets are expensive: ~26+ objects each, henceperPage <= 30)caps
fetchAllat 5 pages per tool (output is meant for an LLM context, so it stays around 100 KB of compact JSON) and reportstruncated: truewhen 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 # prettierGraphQL 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
Available Tools
15 toolsget_eventGet eventARead-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 entrantsBRead-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 setsARead-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 standingsARead-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 playerARead-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 setsARead-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 queueARead-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 tournamentARead-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 participantsARead-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 eventsARead-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 videogameARead-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 tournamentsARead-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 URLARead-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 tournamentsARead-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 videogamesARead-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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Search MCP servers, agent skills and AI tools by task. Read-only, no API key.
Find MCP servers, APIs, tools and skills by intent. Free key: POST /api/agents/register
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Search your video library with natural language and retrieve relevant moments through MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides 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.1Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI assistants to query the FACEIT platform for players, matches, hubs, and tournaments through typed MCP tools generated from the FACEIT Data API v4.64MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query Riot Games data such as accounts, summoners, match history, and champion mastery via natural language.126 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables querying Chess.com player profiles, ratings, game histories, and leaderboard rankings through a natural language MCP interface.95 npmMIT