startgg-mcp-server

一个用于 start.gg GraphQL API 的 Model Context Protocol 服务器。它让 MCP 客户端（Claude Code、Claude Desktop 等）能够使用自然语言发现锦标赛、查看赛事、参赛者、比赛、排名和直播流，适用于 start.gg 上的任何游戏。

这是什么？

start.gg 暴露了一个强大但复杂的 GraphQL API：参赛者 vs 参与者 vs 玩家、整数比赛状态、复杂度限制的分页、纪元时间戳。该服务器将该 API 封装为一小组 MCP 工具，具有：

• 规范化输出 — 比赛以 { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } 的形式返回，而不是原始的 GraphQL 嵌套

• URL 解析 — 粘贴 start.gg URL，即可获得锦标赛/赛事 ID

• 内置限流、重试和缓存，针对 start.gg 的文档化限制进行了调优

该服务器与游戏无关。游戏特定的逻辑（例如 Smash 爆冷检测）属于构建在其之上的应用程序 — 参见 examples/smash-ultimate-watcher。

Related MCP server: Start.gg MCP Server

功能

• 15 个只读工具，涵盖发现、锦标赛、赛事、玩家、直播流和 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 令牌永远不会出现在输出、日志或错误消息中

要求

• Node.js >= 20

• 一个 start.gg API 令牌

获取 start.gg API 令牌

1. 登录 start.gg

2. 打开 开发者设置（个人资料 → 开发者设置）

3. 创建个人访问令牌并复制

将令牌视为密码。该服务器仅从 STARTGG_TOKEN 环境变量中读取它。

安装

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 -- node /path/to/startgg-mcp-server/dist/cli.js

Claude Desktop

添加到 claude_desktop_config.json：

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

任何支持 stdio 服务器的 MCP 客户端都以相同方式工作：运行 node dist/cli.js（或通过 npm 安装后的 startgg-mcp-server bin），并设置 STARTGG_TOKEN。

可用工具

发现

锦标赛

赛事

玩家

工具

锦标赛/赛事工具接受数字 ID、slug 或完整的 start.gg URL — 你很少需要显式调用 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 的取消资格标记

• 未开始的“预览”比赛具有字符串 ID，如 "preview_3430499_2_0"

• state 名称从整数 stateRaw 解码；两者始终返回

• entrant1/entrant2 使用 players 数组，因此双打/团队无需更改即可工作

示例

连接后可以询问 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。

环境变量

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

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

安全

• 令牌仅从环境读取，仅发送到 api.start.gg，绝不会包含在工具输出、日志或错误消息中

• 所有工具均为只读；未实现任何变更操作

• .env 文件被 git 忽略；使用 .env.example 作为模板

• 用户输入在构建任何请求之前经过模式验证

速率限制

start.gg 允许 每 60 秒 80 个请求，每个请求最多 1000 个对象。该服务器：

• 保持滑动窗口预算低于请求限制（默认 75/60 秒）

• 重试 429（遵循 Retry-After）和瞬时 5xx 错误，采用指数退避，最多重试 3 次 — GraphQL 错误从不重试

• 按工具限制 perPage，使响应保持在 1000 对象复杂度限制以下（比赛开销较大：每个约 26+ 个对象，因此 perPage <= 30）

• 将 fetchAll 限制在固定的页面预算内，并在提前停止时报告 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