start.gg MCP Server

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.

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: AUTHERROR, RATELIMITED, NOTFOUND, INVALIDINPUT, STARTGGGRAPHQLERROR, NETWORKERROR, INTERNALERROR
• 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

From npm (recommended)

# 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 claudedesktopconfig.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

Shortened. The full README is on GitHub.