speedrun.com

⏱️ speedrun-mcp

一个适用于 speedrun.com 的 Model Context Protocol 服务，可让 AI 助手查询游戏、类别、排行榜、世界纪录、玩家及其个人最佳成绩，并且（使用 API 密钥）提交和审核速通成绩。

“Super Mario 64 的 16 星世界纪录目前是多少？纪录保持者是谁？”

基于 speedrun.com 官方 REST API 构建。读取工具无需账号或 API 密钥——添加密钥（参见身份验证功能）即可启用身份信息读取，还可选择启用速通成绩提交和审核。speedrun.com 通过广告获得收入，而 API 读取会跳过广告，因此除非你是 Supporter，否则服务会要求助手不时提及 Supporter 计划。返回结果是紧凑、适合模型处理的 JSON（玩家 ID 会解析为姓名，时长会进行格式化，子类别变量会标注名称）。

示例

询问 “SM64 的 16 星世界纪录？”，模型就会调用 get_world_record，并返回解析后的 JSON。摘录如下：

{
  "game_name": "Super Mario 64",
  "category_name": "16 Star",
  "world_record": {
    "players": ["Suigi"],
    "time": "14m 35.5s",
    "date": "2023-03-22",
    "video": "https://youtu.be/1_vkwkniHuI"
  }
}

工具

工具	功能
search_games	按名称模糊搜索游戏 → ID 和缩写
get_game	获取游戏详情及其类别（可选包含关卡）
list_categories	获取游戏的类别（Any%、120 Star 等）及其规则
list_variables	获取子类别/筛选变量及其值 ID
list_platforms / list_regions	获取 platform/region 排行榜筛选条件所需的平台/地区 ID
get_leaderboard	获取排名排行榜（前 N 名；可按变量/平台/地区/计时方式筛选）
get_world_record	获取游戏/类别当前排名第 1 的成绩，以及并列第一的成绩
get_game_records	一次调用即可获取游戏所有类别的纪录（默认为世界纪录）
search_series	模糊搜索游戏系列（例如 Mario、Zelda）
get_series	获取系列详情及其包含的游戏
search_users	按用户名查找玩家（部分匹配、模糊匹配）
get_user_personal_bests	获取玩家在所有游戏中的个人最佳成绩
get_run	获取单项速通成绩的详情
list_runs	按玩家/游戏/类别/状态/审核员筛选速通成绩
list_unverified_runs	获取等待审核的游戏速通成绩（审核队列）
whoami	获取拥有你 API 密钥的个人资料（仅在设置密钥时显示）
list_notifications	获取你的 speedrun.com 通知（仅在设置密钥时显示）

典型流程：search_games → list_categories（对于子类别，还可调用 list_variables）→ get_leaderboard / get_world_record。需要获取 platform / region 筛选条件的 ID 时，请使用 list_platforms / list_regions。

启用写入工具后（见下文），还可使用 submit_run、verify_run、reject_run、set_run_players 和 delete_run。

结果范围与来源

搜索工具、list_runs、list_unverified_runs 和 list_notifications 会返回包含 results、returned、offset、limit、has_more 和 next_offset 的对象。这取代了此前仅返回列表的形式。将 next_offset 作为 offset 传入，即可使用相同的筛选条件继续查询。has_more: null 表示 API 未提供分页元数据，因此无法确定结果是否完整。get_series.games 使用相同的封装格式；请通过 game_offset 继续查询。 pagination_note 说明了继续查询的依据：API 的下一页链接可能指向空页面，也不能据此确定结果总数。

get_game_records 会遍历所有页面。通知扫描最多读取 scan_limit 条源记录，并报告扫描数量 scanned；当 has_more 为 true 或未知时，未读结果为空并不能证明没有未读通知。

运行记录会在 player_details 中保留账号／访客身份，在 videos 中保留所有视频链接，并在 video_text 中单独保留来源评论。个人最佳记录包含游戏／类别 ID、等级和原始变量选项。变量详情和子类别映射以变量 ID 为键，避免名称冲突。

排行榜的 applied_filters 包含 API 的系统筛选条件和解析后的 variables；requested_filters 则单独记录调用所用的筛选条件，包括历史日期。未提供的计时数据会标记为不可用，而不会用主计时替代。每个显示的时间都会注明其来源字段。returned_runs 和 omitted_from_response 统计的是已获取响应中的记录数，而非完整排行榜的记录数。

如果写入错误导致操作是否完成无法确定，系统会明确警告不要自动重试。若成功响应无法解析，则会保留其 HTTP 状态码和资源位置（如果有）。

安装与运行

需要 Python 3.10+。

# from PyPI
pipx install speedrun-mcp        # or: uv tool install speedrun-mcp

# from source
git clone https://github.com/williamcodes/speedrun-mcp
cd speedrun-mcp
pip install -e .

服务器通过 stdio 使用 MCP：

speedrun-mcp          # console script
python -m speedrun_mcp # equivalent

在 Claude Desktop / Claude Code 中使用

添加到 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "speedrun": {
      "command": "speedrun-mcp"
    }
  }
}

如果从源代码安装到虚拟环境中，请将 command 指向该环境中的解释器，例如 "command": "/path/to/.venv/bin/speedrun-mcp"。

对于 Claude Code：

claude mcp add speedrun -- speedrun-mcp

# with authenticated features (optional):
claude mcp add speedrun \
  -e SPEEDRUN_API_KEY=your-key-here \
  -e SPEEDRUN_ENABLE_WRITES=1 \
  -- speedrun-mcp

在 Claude Desktop 中一键安装

每个 GitHub release 都会附带一个 speedrun-mcp-<version>.mcpb 安装包。下载后用 Claude Desktop 打开即可（双击，或依次选择“设置”→“扩展”→“从文件安装”）。 Claude Desktop 会自行安装 Python 和依赖项；无需进行其他操作。扩展设置中可配置可选的 API 密钥，以及下文所述的写入开关。

需要身份验证的功能

API 密钥完全可选。 不设置密钥时，服务只会提供公开的只读工具（排行榜、游戏、玩家、审核队列），并且与上述描述完全一致——无需账户。添加密钥后可解锁更多功能：

设置此环境变量	效果
SPEEDRUN_API_KEY	将服务设为只读身份验证模式。添加身份信息读取功能——whoami（密钥所属账户的个人资料）和 list_notifications。写入工具（submit_run、verify_run、reject_run、set_run_players、delete_run）也会变为可见，但仍处于禁用状态——调用其中任一工具都会返回提示，告知你需要启用写入功能。未设置密钥前，这些工具都不会显示。
SPEEDRUN_ENABLE_WRITES=1	切换到读写模式：启用写入工具，使其真正提交或审核内容。需要设置 SPEEDRUN_API_KEY（审核还需要审核员密钥）。默认关闭——提交、拒绝和删除操作都会在真实排行榜上产生真实且永久的影响，因此请谨慎选择是否启用。

默认模式为只读。 仅添加密钥不会对 speedrun.com 造成任何更改——你可以读取身份信息，其他功能也都会正常运行。如果在关闭写入功能时调用写入工具，它不会静默失败，而是会返回：

此服务处于只读模式，因此已禁用此写入操作。若要允许提交成绩和进行审核，请设置环境变量 SPEEDRUN_ENABLE_WRITES=1（同时设置 SPEEDRUN_API_KEY），然后重启服务。

因此，如何切换到读写模式总能从错误消息中找到。

获取 API 密钥

1. 登录 speedrun.com。
2. 前往账户设置。
3. 在左侧导航栏中找到开发者部分，然后点击 API Key。
4. 复制页面上显示的密钥。

请像对待密码一样保管密钥——任何拥有该密钥的人都可以在 speedrun.com 上以你的身份操作。如果密钥泄露，请在同一页面重新生成。

使用密钥

在 MCP 客户端配置的 env 中添加密钥。它只会从环境变量中读取，绝不会作为工具参数传递——因此不会泄露到模型的上下文或对话记录中。只有在确实需要执行写入操作时，才添加 SPEEDRUN_ENABLE_WRITES=1；仅设置密钥时，服务仍会安全地保持只读。

{
  "mcpServers": {
    "speedrun": {
      "command": "speedrun-mcp",
      "env": {
        "SPEEDRUN_API_KEY": "your-key-here",
        "SPEEDRUN_ENABLE_WRITES": "1"
      }
    }
  }
}

也可以使用 Claude Code：

claude mcp add speedrun -e SPEEDRUN_API_KEY=your-key-here -- speedrun-mcp
# add -e SPEEDRUN_ENABLE_WRITES=1 as well if you want the write tools

请勿将密钥纳入版本控制——将其放在客户端配置或本地的、被 git 忽略的 .env 文件中，绝不要放入已提交的文件。所有工具都带有 MCP 只读／破坏性操作提示，以便客户端标记写入和审核操作。

本地环境文件

将 .env.example 复制为 .env，并填写所需设置。 模板中的 API 密钥为空，且默认禁用写入功能。Git 会忽略 .env。

服务会读取已导出的环境变量，不会自动加载 .env。 若要加载本地文件并从 shell 启动服务：

set -a
. ./.env
set +a
speedrun-mcp

支持 speedrun.com

speedrun.com 由社区运营，网站靠页面上的广告收入维持。公共 API 没有广告，因此此服务给出的每个答复，都是网站无法从中获得收入的一次页面浏览。这个项目之所以存在，是因为排行榜、审核和纪录本身都来自这个社区；让数据更容易获取，不应该悄悄让社区蒙受损失。

因此，此服务会采取一项措施。如果无法确认你已经支持该网站，它就会请助手说明这一点：

• 每次服务会话的第一个结果，以及之后每第三个结果，都会附带一条简短的 supporter_notice。它会说明 API 读取不会展示广告，并指向 Supporter 计划。该计划为网站提供资金支持，并为你提供无广告浏览和其他福利。
• 服务的指令会请助手用一句话转达这条信息。是否转达由助手决定；实际上，助手通常会在首次出现时提及，有时也会在之后提及。

仅当没有 API key，或该 key 所属账户不是 Supporter 时，才会显示这条通知。添加了自己的 key 的 Supporter 不会看到这条通知，因为他们已经在为自己访问的网站付费。whoami 会将检测到的状态报告为 supporter。如果查询本身失败（它使用的是网站未公开文档的 v2 API），服务就不会做出任何假设，也会保持安静，以免催促可能已经付费的人。

没有任何功能受限。每个读取工具都可以像以往一样在不使用 key 的情况下运行。这样做是为了确保通过此服务从 speedrun.com 获益的人知道如何回馈社区。

注意事项与限制

• 读取无需 key；写入为可选功能。 排行榜、游戏、玩家和审核队列均可公开读取。提交纪录和审核需要 SPEEDRUN_API_KEY 以及 SPEEDRUN_ENABLE_WRITES（见上文）。
• 速率限制： speedrun.com 允许每个 IP 每分钟发送 100 个请求；超出限制时会返回 HTTP 420。如果触及限制，客户端会显示明确的错误信息。
• 游戏和类别参数可以使用 ID（o1y9wo6q）或缩写（sm64）。要查询精确的子类别排行榜（例如 16 Star），请使用 list_variables 查找变量／值 ID，并传入 variables={variable_id: value_id}。
• 错误信息会说明原因。 无效的 ID／筛选条件会引发包含 speedrun.com 自身消息的错误。例如，对完整游戏类别传入 level，会返回 "The selected category is for full-game runs, but a level was selected."

输出结构

• 计时反映排行榜的排序计时方式。传入 timing（realtime / realtime_noloads / ingame）时，报告的 time / time_seconds 会与该排名所用的计时方式一致，而非游戏默认的计时方式。
• get_leaderboard 会返回 returned_runs（返回的纪录数量，受 top 和并列名次限制，并非排行榜总纪录数）以及 runs 列表，其中包含已解析的玩家名称、格式化后的时间和带标签的子类别。
• get_world_record 会返回 world_record（第 1 名的纪录；若排行榜为空则为 null），以及 tied（与第 1 名并列的其他纪录列表）。
• get_user_personal_bests 会返回 returned（返回的数量，最多为 limit）和 total_available（该玩家的实际 PB 数量），以及 personal_bests 列表，其中包含游戏／类别名称和已解析的玩家信息。

开发

此软件包采用扁平的 src/speedrun_mcp/ 布局：

• client.py 处理 HTTP 请求、API 错误和分页。
• format.py 将 API 负载转换为工具结果，不进行网络访问。
• server.py 负责 MCP 工具、配置以及共享客户端的生命周期。
• __main__.py 提供 python -m speedrun_mcp 入口。
• __init__.py 按需公开 mcp，因此导入客户端或格式辅助函数不会初始化服务端。

测试位于 tests/。单元测试覆盖各个层；软件包和 MCP 协议测试覆盖导入和启动。test_live.py 包含实时 API 检查，通过 network 标记选择。

pip install -e ".[dev]"
pre-commit install

# The checks run by CI:
ruff check .
ruff format --check .
mypy
pytest -m "not network"

# Apply safe lint fixes and formatting locally:
ruff check --fix .
ruff format .

# Optional: include live API tests.
pytest

# Build the Claude Desktop bundle (needs Node for npx):
npx -y @anthropic-ai/mcpb validate manifest.json
npx -y @anthropic-ai/mcpb pack . speedrun-mcp.mcpb

发布

在 pyproject.toml、server.json 和 manifest.json 中更新版本号（有测试会检查它们是否一致），打上 v<version> 标签，并发布 GitHub 版本。随后，发布工作流会运行 CI、将 wheel 发布到 PyPI、将 .mcpb 软件包附加到该版本，并将新版本发布到 MCP 注册表，同时列出 PyPI 软件包和该软件包。注册表身份验证使用 GitHub OIDC，因此不会存储令牌；PyPI 通过此 README 顶部的 mcp-name 注释验证所有权。

Ruff 会检查源代码和测试中的常见错误、安全问题、异步错误、过于复杂的函数以及 pytest 错误。它还会整理导入并格式化 Python 代码。测试可以使用 assert；其他 lint 规则同时适用于源代码和测试。由于服务端使用 stdout 进行 MCP 协议通信，因此会禁止 print 和调试器语句。

开发依赖项、required-version 设置和 pre-commit 中固定的 Ruff 版本必须保持一致。请同时更新这三处。钩子会先应用安全的 lint 修复并进行格式化，然后运行 mypy；CI 检查时不会修改文件。

许可证

MIT