start.gg MCP Server

startgg-mcp-server

一个用于 start.gg GraphQL API 的 Model Context Protocol 服务。它让 MCP 客户端（Claude Code、Claude Desktop 等）能够通过自然语言发现锦标赛、查看活动、参赛者、对局、排名和直播，支持 start.gg 上的任何游戏。

这是什么？

start.gg 提供了强大但复杂的 GraphQL API：参赛者、参与者和玩家概念各不相同，对局状态使用整数表示，分页受复杂度限制，时间戳使用纪元时间。本服务将该 API 封装为一组精简的 MCP 工具，具备以下特点：

• 规范化输出 — 对局以 { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } 的形式返回，而非原始的 GraphQL 嵌套结构
• URL 解析 — 粘贴 start.gg URL，即可获取锦标赛和活动 ID
• 内置速率限制、重试和缓存，针对 start.gg 公布的限制进行了调优

本服务与游戏无关。游戏特定逻辑（例如 Smash 爆冷检测）应由基于本服务构建的应用实现 — 参见 examples/smash-ultimate-watcher。

功能

• 16 个只读工具，涵盖发现、锦标赛、活动、玩家、直播和 URL 解析
• 每个工具均进行输入验证（Zod）— 错误的 ID、过大的页面大小和格式错误的 URL 都不会发送到 API
• 滑动窗口速率限制器（默认 75 次请求/60 秒，低于 start.gg 的 80 次限制）、指数退避重试，并支持 Retry-After
• 用于元数据查询的短 TTL 内存缓存
• 类型化错误代码：AUTH_ERROR、RATE_LIMITED、NOT_FOUND、INVALID_INPUT、STARTGG_GRAPHQL_ERROR、NETWORK_ERROR、INTERNAL_ERROR
• GraphQL 文档单独存放在 graphql/ 文件中，与代码分离
• API 令牌绝不会出现在输出、日志或错误消息中
• 紧凑的 JSON 输出（不进行美化打印），以缩小工具结果

要求

• Node.js >= 22
• start.gg API 令牌

获取 start.gg API 令牌

1. 登录 start.gg
2. 打开 开发者设置（Profile → Developer Settings）
3. 创建个人访问令牌并复制

请将令牌视同密码。本服务仅从 STARTGG_TOKEN 环境变量读取令牌。

安装

从 npm 安装（推荐）

# run without installing
npx startgg-mcp-server

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

需要在环境中设置 STARTGG_TOKEN；MCP 客户端通常会为你启动服务（见下一节）。

从源代码安装

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

MCP 客户端配置

Claude Code（CLI）

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

改为从源代码检出目录运行：

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

Claude Desktop

在 claude_desktop_config.json 中添加：

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

从源代码检出目录运行时，改用 "command": "node" 和 "args": ["/path/to/startgg-mcp-server/dist/cli.js"]。

任何支持 stdio 服务的 MCP 客户端都可以采用相同方式运行：设置 STARTGG_TOKEN，然后运行 node dist/cli.js（或通过 npm 安装后运行 startgg-mcp-server 可执行文件）。

可用工具

发现

工具	用途
search_videogames	按名称查找电子游戏 ID（例如，“Super Smash Bros. Ultimate” → 1386）
search_tournaments	通用锦标赛搜索：名称、电子游戏、国家/州、日期范围、即将举行/过往、开放报名状态
get_upcoming_tournaments	尚未结束的锦标赛（包括正在进行的锦标赛），按开始时间从近到远排序，并支持设置天数范围
get_tournaments_by_videogame	查找指定电子游戏 ID 对应的锦标赛（即将举行 / 过往 / 全部）

赛事

工具	用途
get_tournament	详情、赛程、场地、赛事列表、已配置的直播流
get_tournament_events	赛事的项目（对阵表），可按电子游戏筛选
get_tournament_entrants	赛事级别的参与者（参赛者）；各项目的种子位于 get_event_entrants 中
get_stream_queue	直播流队列：直播流（含派生的 Twitch URL）及分配给每个直播流的对局

项目

工具	用途
get_event	项目详情，包括阶段（小组赛、Top 8 等）及阶段 ID
get_event_entrants	参赛者及其种子、选手、DQ 标记；支持分页或 fetchAll
get_event_standings	名次（Top 8 可使用 perPage: 8）
get_event_sets	规范化后的对局及其 stream；可按状态、阶段、轮次、参赛者、选手、VOD 筛选；使用 includeGames 获取逐局详情
get_set_games	单场对局中每一局的场地／胜者／角色选择；详见覆盖率说明

选手

工具	用途
get_player	按 ID 查询选手：玩家标签、前缀、关联用户
get_player_sets	选手在各项赛事中的近期对局

实用工具

工具	用途
resolve_startgg_url	start.gg URL／slug → { type, tournamentId, eventId, slugs, names }

赛事／项目工具接受数字 ID、slug 或完整的 start.gg URL。也接受不含 scheme 的 URL（start.gg/tournament/...）和 <t>/event/<e> slug——通常无需显式调用 resolve_startgg_url，但如果需要 ID，可以使用它。

规范化的对局结构

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

基于实时 API 的说明：

• roundNumber < 0 表示败者组；round 是人类可读的名称
• 分数为 -1 表示 start.gg 的取消资格标记
• 尚未开始的“预览”对局使用类似 "preview_3430499_2_0" 的字符串 ID
• state 名称根据整数 stateRaw 解码；两者始终都会返回
• entrant1／entrant2 使用 players 数组，因此双打／团队赛事也无需特殊处理

对局和角色

当 start.gg 提供逐局详情时，get_set_games（以及设置了 includeGames: true 的 get_event_sets）会添加这些详情：

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

derivedCharacters 按照角色首次出现的顺序，汇总每位参赛者在各局中的唯一角色名称。这是派生字段，并非 API 字段。

只有在提交对局报告时包含角色和场地数据，才会有这些数据。在 2026-09 的样本中，已完成的后期轮次（Top 8／直播对局）约有 90% 包含这些数据；早期小组赛约有 5%。games 数组为空表示未提交相关报告，并不代表没有进行过对局。典型流程：调用 get_event_sets（例如使用 phaseIds 筛选 Top 8）→ 选择对局 ID → 调用 get_set_games。要一次处理多场对局，可调用设置了 includeGames: true 的 get_event_sets。

示例

连接后可以向 MCP 客户端询问：

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?

一个独立的示例应用（格斗游戏查询 → 即将举行的锦标赛 → 对局 → 按种子差值筛选爆冷候选者）位于 examples/smash-ultimate-watcher。

环境变量

变量	必填	默认值	用途
STARTGG_TOKEN	是	—	start.gg API 令牌
STARTGG_ENABLE_WRITES	否	false	预留。目前尚无写入工具；此标志仅用于记录提示
STARTGG_RATE_LIMIT	否	75	每 60s 时间窗口内的请求数（硬性上限为 80）
STARTGG_TIMEOUT_MS	否	30000	单次请求的 HTTP 超时时间
STARTGG_CACHE	否	on	设置为 off 以禁用内存缓存

API 端点特意不通过环境变量进行配置：令牌只会发送到 api.start.gg。将客户端用作库时（测试、工具），通过 StartggClient 构造函数注入 apiUrl/fetchFn。

STARTGG_RATE_LIMIT / STARTGG_TIMEOUT_MS 的超出范围或非数字值会回退到默认值，并在 stderr 上记录警告。

没有 STARTGG_TOKEN 时，服务仍会启动并列出工具，但每次调用都会返回清晰的 AUTH_ERROR，说明如何修复。

安全

• 令牌仅读取自环境变量，只会发送到 api.start.gg，绝不会包含在工具输出、日志或错误消息中
• 所有工具均为只读；尚未实现任何修改操作
• .env 文件已被 git 忽略；请使用 .env.example 作为模板
• 用户提供的输入会在构建任何请求之前通过架构验证

速率限制

start.gg 允许每 60 秒 80 个请求，且每个请求最多包含 1000 个对象。此服务：

• 将滑动窗口预算控制在请求上限以下（默认每 60s 75 个请求）
• 遇到 429（遵循 Retry-After）和暂时性 5xx 错误时采用指数退避重试，最多重试 3 次；GraphQL 错误绝不会重试
• 对每个工具的 perPage 设置上限，确保响应不超过 1000 个对象的复杂度限制（对局开销较大：每个约含 26 个以上对象，因此 perPage <= 30）
• 将每个工具的 fetchAll 限制为 5 页（输出面向大模型上下文，因此精简 JSON 的大小保持在约 100 KB），并在提前停止时报告 truncated: true

开发

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 文档位于 graphql/*.graphql（每个领域一个文件，每个文件可包含多个命名操作；请求通过 operationName 选择操作）。 已通过实时 API 验证的架构信息记录在 docs/startgg-api-notes.md 中——添加字段前请先阅读。

测试

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)

单元测试涵盖 URL 解析器、规范化器、输入验证、分页、GraphQL/HTTP 错误处理、速率限制器和缓存。

许可证

MIT