startgg-mcp-server

Un servidor del Model Context Protocol para la API GraphQL de start.gg. Permite que los clientes MCP (Claude Code, Claude Desktop y otros) descubran torneos, inspeccionen eventos, participantes, sets, clasificaciones y streams de cualquier juego en start.gg usando lenguaje natural.

¿Qué es esto?

start.gg expone una API GraphQL potente pero compleja: entrants vs participants vs players, estados de set enteros, paginación con límite de complejidad, marcas de tiempo epoch. Este servidor envuelve esa API en un pequeño conjunto de herramientas MCP con:

• Salida normalizada — los sets se devuelven como { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } en lugar del anidamiento GraphQL crudo

• Resolución de URLs — pega una URL de start.gg y obtén los ids de torneo/evento

• Límite de tasa, reintentos y caché integrados ajustados a los límites documentados de start.gg

El servidor es independiente del juego. La lógica específica de un juego (p. ej., detección de sorpresas en Smash) pertenece a las aplicaciones construidas sobre él — ver examples/smash-ultimate-watcher.

Related MCP server: Start.gg MCP Server

Características

• 15 herramientas de solo lectura que cubren descubrimiento, torneos, eventos, jugadores, streams y resolución de URLs

• Validación de entrada (Zod) en cada herramienta — los ids incorrectos, tamaños de página excesivos y URLs malformadas nunca llegan a la API

• Limitador de tasa de ventana deslizante (por defecto 75 req/60s frente a los 80 de start.gg), reintentos con retroceso exponencial y soporte de Retry-After

• Caché en memoria con TTL corto para consultas de metadatos

• Códigos de error tipados: AUTH_ERROR, RATE_LIMITED, NOT_FOUND, INVALID_INPUT, STARTGG_GRAPHQL_ERROR, NETWORK_ERROR, INTERNAL_ERROR

• Documentos GraphQL mantenidos en archivos graphql/, separados del código

• El token de la API nunca aparece en la salida, los registros o los mensajes de error

Requisitos

• Node.js >= 20

• Un token de API de start.gg

Cómo obtener un token de API de start.gg

1. Inicia sesión en start.gg

2. Abre developer settings (Perfil → Configuración de desarrollador)

3. Crea un token de acceso personal y cópialo

Trata el token como una contraseña. Este servidor solo lo lee de la variable de entorno STARTGG_TOKEN.

Instalación

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

Configuración del cliente MCP

Claude Code (CLI)

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

Claude Desktop

Añade a claude_desktop_config.json:

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

Cualquier cliente MCP que admita servidores stdio funciona de la misma manera: ejecuta node dist/cli.js (o el binario startgg-mcp-server una vez instalado vía npm) con STARTGG_TOKEN configurado.

Herramientas disponibles

Descubrimiento

Torneo

Evento

Jugador

Utilidad

Las herramientas de torneo/evento aceptan ya sea un id numérico, un slug o una URL completa de start.gg — rara vez necesitarás resolve_startgg_url explícitamente, pero está ahí cuando quieras los ids.

Forma normalizada de los sets

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

Notas basadas en la API en vivo:

• roundNumber < 0 significa bracket de perdedores; round es el nombre legible

• una puntuación de -1 es el marcador de descalificación de start.gg

• los sets "preview" no iniciados tienen ids de cadena como "preview_3430499_2_0"

• los nombres de state se decodifican del entero stateRaw; ambos se devuelven siempre

• entrant1/entrant2 usan un array players, por lo que los dobles/equipos funcionan sin cambios

Ejemplos

Cosas que puedes pedir a un cliente MCP una vez conectado:

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?

Una aplicación de ejemplo independiente (búsqueda de videojuego → próximos torneos → sets → candidatos a sorpresa por diferencia de siembra) está en examples/smash-ultimate-watcher.

Variables de entorno

El endpoint de la API no es configurable deliberadamente a través del entorno: el token solo se envía a api.start.gg. Cuando se usa el cliente como biblioteca (pruebas, herramientas), inyecta apiUrl/fetchFn mediante el constructor StartggClient.

Sin STARTGG_TOKEN, el servidor aún se inicia y lista las herramientas, pero cada llamada devuelve un AUTH_ERROR claro que explica cómo solucionarlo.

Seguridad

• El token se lee solo del entorno, se envía solo a api.start.gg y nunca se incluye en la salida de las herramientas, los registros o los mensajes de error

• Todas las herramientas son de solo lectura; no se implementan mutaciones

• Los archivos .env están en git-ignore; usa .env.example como plantilla

• La entrada proporcionada por el usuario se valida con esquema antes de construir cualquier solicitud

Límites de tasa

start.gg permite 80 solicitudes por 60 segundos y como máximo 1000 objetos por solicitud. Este servidor:

• mantiene un presupuesto de ventana deslizante por debajo del límite de solicitudes (por defecto 75/60s)

• reintenta 429 (respetando Retry-After) y errores 5xx transitorios con retroceso exponencial, como máximo 3 reintentos — los errores GraphQL nunca se reintentan

• limita perPage por herramienta para que las respuestas se mantengan bajo el límite de complejidad de 1000 objetos (los sets son costosos: ~26+ objetos cada uno, por lo tanto perPage <= 30)

• limita fetchAll a un presupuesto de páginas fijo e informa truncated: true cuando se detiene antes

Desarrollo

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

Los documentos GraphQL viven en graphql/*.graphql (un archivo por dominio, múltiples operaciones nombradas por archivo; las solicitudes seleccionan una operación mediante operationName). Los hechos del esquema verificados contra la API en vivo se registran en docs/startgg-api-notes.md — léelo antes de añadir campos.

Pruebas

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)

Las pruebas unitarias cubren el resolvedor de URLs, los normalizadores, la validación de entrada, la paginación, el manejo de errores GraphQL/HTTP, el limitador de tasa y la caché.

Licencia

MIT