speedrun-mcp
This server lets an AI assistant query and (optionally, opt-in) moderate speedrun.com data through MCP.
Fuzzy-search games and game series by name, and get game details with categories and levels.
List a game's categories, subcategory variables, platforms, and regions.
Fetch ranked leaderboards and world records with filters (platform, region, timing, emulators, subcategory variables, historical date).
Get every category's records for a game in one call, including individual-level boards.
Search users and retrieve a player's personal bests across all games.
Get details of single runs, list runs filtered by player/game/category/status/examiner, and view a game's unverified moderation queue.
With an optional API key: identify the authenticated profile and list notifications.
With both an API key and
SPEEDRUN_ENABLE_WRITES=1: submit, verify, reject, set players on, and delete runs (real, permanent actions).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@speedrun-mcp What's the current world record for Super Mario 64 16-star?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⏱️ speedrun-mcp
A Model Context Protocol server for speedrun.com — let an AI assistant query games, categories, leaderboards, world records, players and their personal bests, and (with an API key) submit and moderate runs.
"What's the current Super Mario 64 16-star world record, and who holds it?"
Built on speedrun.com's official REST API. The read tools need no account or API key — add a key (see Authenticated features) to unlock identity reads and, optionally, run submission and moderation. speedrun.com is ad-funded and API reads skip the ads, so unless you are a Supporter the server asks the assistant to mention the Supporter program now and then. Results come back as compact, model-friendly JSON (player ids resolved to names, durations formatted, subcategory variables labeled).
Example
Ask "the SM64 16-star world record?" and the model calls get_world_record,
which returns resolved JSON. An excerpt:
{
"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"
}
}Related MCP server: Chess MCP Server
Tools
Tool | What it does |
| Fuzzy-search games by name → ids & abbreviations |
| A game's details plus its categories (and optionally levels) |
| A game's categories ( |
| Subcategory/filter variables and their value ids |
| Platform / region ids for the |
| A ranked leaderboard (top N; filter by variable / platform / region / timing) |
| The current #1 run for a game/category, plus any runs tied for first |
| Every category's records for a game in one call (defaults to world records) |
| Fuzzy-search game series (e.g. |
| A series' details and the games it contains |
| Find players by username (partial, fuzzy match) |
| A player's PBs across all games |
| Details of a single run |
| Runs filtered by player / game / category / status / examiner |
| A game's runs awaiting verification (the moderation queue) |
| The profile that owns your API key (only shown when a key is set) |
| Your speedrun.com notifications (only shown when a key is set) |
A typical flow: search_games → list_categories (and list_variables for
subcategories) → get_leaderboard / get_world_record. Use list_platforms /
list_regions when you need an id for the platform / region filters.
With write tools enabled (see below), submit_run, verify_run, reject_run,
set_run_players and delete_run are also available.
Result scope and provenance
Search tools, list_runs, list_unverified_runs, and list_notifications return
an object with results, returned, offset, limit, has_more, and
next_offset. This replaces their earlier bare-list output. Pass next_offset
as offset to continue with the same filters. has_more: null means the API
omitted pagination metadata, so completeness is unknown. get_series.games
uses the same envelope; continue with game_offset.
pagination_note explains the continuation evidence: an API next-page link
can lead to an empty page and does not establish a total result count.
get_game_records follows all pages. Notifications scan up to scan_limit
source records and report scanned; an empty unread result is not evidence of
no unread notifications when has_more is true or unknown.
Run rows preserve account/guest identity in player_details, all video links
in videos, and separate source commentary in video_text. Personal-best rows
include game/category IDs, level, and raw variable choices. Variable details and
subcategory maps are keyed by variable ID to avoid collisions between names.
Leaderboard applied_filters includes the API's system filters and resolved
variables; requested_filters separately records the call's filters, including
historical dates. A missing requested timing is marked unavailable rather than
replaced by the primary time. Each displayed time identifies its source field.
returned_runs and omitted_from_response count rows from the fetched response,
not the full leaderboard.
Write errors that leave completion uncertain explicitly warn against automatic retries. A success response that cannot be parsed preserves its HTTP status and resource location when supplied.
Install & run
Requires 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 .The server speaks MCP over stdio:
speedrun-mcp # console script
python -m speedrun_mcp # equivalentUse with Claude Desktop / Claude Code
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"speedrun": {
"command": "speedrun-mcp"
}
}
}If you installed from source into a virtualenv, point command at that
interpreter, e.g. "command": "/path/to/.venv/bin/speedrun-mcp".
For 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-mcpOne-click install in Claude Desktop
Each GitHub release
ships a speedrun-mcp-<version>.mcpb bundle. Download it and open it with
Claude Desktop (double-click, or Settings → Extensions → Install from file).
Claude Desktop installs Python and the dependencies itself; nothing else is
needed. The extension settings expose the optional API key and the writes
toggle described below.
Authenticated features
An API key is entirely optional. With no key, the server exposes only the public read tools (leaderboards, games, players, the moderation queue) and works exactly as described above — no account required. Adding your key unlocks more:
Set this env var | Effect |
| Puts the server in read-only authenticated mode. Adds the identity reads — |
| Switches to read-write mode: arms the write tools so they actually submit/moderate. Requires |
Read-only is the default. Just adding a key never changes anything on speedrun.com — you get identity reads, and everything keeps working perfectly. If a write tool is invoked while writes are off, it doesn't silently fail; it returns:
This server is in read-only mode, so this write action is disabled. To allow run submission and moderation, set the environment variable SPEEDRUN_ENABLE_WRITES=1 (alongside SPEEDRUN_API_KEY) and restart the server.
So the way to switch to read-write mode is always discoverable from the error itself.
Getting your API key
Log in to speedrun.com.
Go to your account settings.
In the left-hand nav, find the Developers section and click API Key.
Copy the key shown there.
Treat the key like a password — anyone who has it can act as you on speedrun.com. If it ever leaks, regenerate it from that same page.
Using your key
Add the key to your MCP client config under env. It is read only from the
environment — never passed as a tool argument — so it can't leak into the
model's context or transcripts. Add SPEEDRUN_ENABLE_WRITES=1 only when you want
writes to actually run; with the key alone you stay safely read-only.
{
"mcpServers": {
"speedrun": {
"command": "speedrun-mcp",
"env": {
"SPEEDRUN_API_KEY": "your-key-here",
"SPEEDRUN_ENABLE_WRITES": "1"
}
}
}
}Or with 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 toolsKeep the key out of version control — put it in your client config or a local,
git-ignored .env, never in a committed file. All tools carry MCP read-only /
destructive hints so clients can flag the write and moderation actions.
Local environment file
Copy .env.example to .env and fill in the settings you need.
The template leaves the API key empty and disables writes. Git ignores .env.
The server reads exported environment variables and does not load .env
automatically. To load your local file and start the server from a shell:
set -a
. ./.env
set +a
speedrun-mcpSupporting speedrun.com
speedrun.com is run for the community and paid for by the ads on its pages. The public API has no ads, so every answer this server gives is a page view the site never gets paid for. This project exists because the leaderboards, the moderation, and the records themselves come from that community, and it should not quietly cost them money to make the data easier to reach.
So the server does one thing about it. When it cannot tell that you already support the site, it asks the assistant to say so:
The first result of a server session, and every third result after that, carries a short
supporter_notice. It explains that API reads skip the ads and points to the Supporter program, which funds the site and gives you ad-free browsing and other perks.The server's instructions ask the assistant to pass that along in a sentence. Whether it does is up to the assistant; in practice it mentions it on the first occurrence and sometimes on later ones.
The notice appears only when there is no API key, or when the key's account is
not a Supporter. Supporters who add their key never see it, because they are
already paying for the site they are reading. whoami reports the detected
status as supporter. If the lookup itself fails (it uses the site's
undocumented v2 API), the server assumes nothing and stays quiet rather than
nag someone who may already be paying.
Nothing is gated. Every read tool works without a key, as it always has. The point is to make sure that people who get value from speedrun.com through this server know how to give something back.
Notes & limits
Reads need no key; writes are opt-in. Leaderboards, games, players and the moderation queue are open reads. Run submission and moderation need
SPEEDRUN_API_KEYandSPEEDRUN_ENABLE_WRITES(see above).Rate limit: speedrun.com allows 100 requests/minute per IP and responds with HTTP 420 when exceeded; the client surfaces a clear error if you hit it.
Game and category arguments accept either an id (
o1y9wo6q) or an abbreviation (sm64). For precise subcategory leaderboards (e.g.16 Star), discover the variable/value ids withlist_variablesand passvariables={variable_id: value_id}.Errors are explanatory. Invalid ids/filters raise an error that includes speedrun.com's own message — e.g. passing a
levelto a full-game category returns "The selected category is for full-game runs, but a level was selected."
Output shape
Times reflect the leaderboard's sort timing. When you pass
timing(realtime/realtime_noloads/ingame), the reportedtime/time_secondsmatch that ranking, not the game's default timing.get_leaderboardreturnsreturned_runs(the number of runs returned, bounded bytopand ties — not the full board size) and arunslist with resolved player names, formatted times, and labeled subcategories.get_world_recordreturnsworld_record(the place-1 run, ornullif the board is empty) plustied(a list of any other runs sharing first place).get_user_personal_bestsreturnsreturned(how many came back, capped bylimit) andtotal_available(the player's true PB count), plus thepersonal_bestslist with game/category names and resolved players.
Development
The package uses a flat src/speedrun_mcp/ layout:
client.pyhandles HTTP requests, API errors, and pagination.format.pyconverts API payloads into tool results without network access.server.pyowns MCP tools, configuration, and the shared client's lifecycle.__main__.pyprovides thepython -m speedrun_mcpentry point.__init__.pyexposesmcpon demand, so importing the client or format helpers does not initialize the server.
Tests live in tests/. Unit tests cover each layer; package and MCP protocol
tests cover imports and startup. test_live.py contains the live API checks,
selected with the network marker.
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.mcpbReleasing
Bump the version in pyproject.toml, server.json and manifest.json (a test
checks they agree), tag v<version>, and publish a GitHub release. The release
workflow then runs CI, publishes the wheel to PyPI, attaches the .mcpb bundle
to the release, and publishes the new version to the
MCP registry with both the PyPI
package and the bundle listed. Registry auth uses GitHub OIDC, so no token is
stored; PyPI verifies ownership through the mcp-name comment at the top of
this README.
Ruff checks source and tests for common bugs, security issues, async mistakes,
overly complex functions, and pytest mistakes. It also sorts imports and formats
Python code. Tests may use assert; the other lint rules apply to both source
and tests. Print and debugger statements are rejected because the server uses
stdout for the MCP protocol.
Ruff is pinned to the same version in the dev dependencies, its required-version
setting, and pre-commit. Update all three together. The hooks apply safe lint fixes
and formatting before running mypy; CI checks without changing files.
License
MIT
Available Tools
16 toolsget_gameARead-only
Get a game's details plus its categories (and optionally its levels).
The embedded categories give you the category_id needed for
get_leaderboard.
Inputs: game (required), include_levels.
get_game_recordsARead-only
Get a game's records across all its categories in one call.
With top=1 (default) this is every category's world record at once —
handy for "show me all the records for ". include_levels=True also
pulls every individual-level board, which can be large for level-heavy games.
Inputs: game (required), top, include_levels.
get_leaderboardARead-only
Get a ranked leaderboard for a game/category (full-game or individual level).
Players, subcategory labels and the category name are resolved for you. For
subcategory filters, discover ids with list_variables first.
Inputs: game (required), category (required), top, date, +6 more.
get_runARead-only
Get a run's players, times, game/category, status, system and variable values.
Inputs: run_id (required).
get_seriesARead-only
Get a series' details and (by default) the games it contains.
The returned game ids/abbreviations feed the other tools (get_game,
list_categories, get_leaderboard).
Inputs: series (required), game_limit, game_offset, include_games.
get_user_personal_bestsARead-only
Get a player's personal best runs across all games, with game/category names.
/personal-bests is unpaginated, so total_available is the player's true
PB count and returned is how many came back after applying limit.
Inputs: user (required), limit.
get_world_recordARead-only
Get the current world record (place 1) for a game/category.
A convenience wrapper over get_leaderboard. Returns the leaderboard
metadata plus world_record (the single fastest run, or None if the
leaderboard is empty) and tied (any other runs also at place 1; usually
empty).
Inputs: game (required), category (required), level, variables.
list_categoriesARead-only
List a game's categories (e.g. 'Any%', '120 Star'), with their ids and rules.
Inputs: game (required). Returns: result
list_platformsARead-only
List speedrun.com platforms (consoles/systems) with their ids and names.
Use a returned id as the platform filter for get_leaderboard
(the leaderboard API requires the platform id, not its name).
Inputs: no named parameters. Returns: result
list_regionsARead-only
List speedrun.com regions (e.g. USA/NTSC, EUR/PAL) with their ids and names.
Use a returned id as the region filter for get_leaderboard
(the leaderboard API requires the region id, not its name).
Inputs: no named parameters. Returns: result
list_runsARead-only
List runs with filters — e.g. a player's recent submissions, or a game's verified/rejected runs. Newest first; combine filters to narrow down.
For just one game's moderation queue, list_unverified_runs is simpler.
Inputs: game, user, limit, offset, +3 more.
list_unverified_runsARead-only
List a game's runs awaiting verification — the moderation queue.
A public read (no API key needed). Pair with verify_run / reject_run
(which do require a moderator key) to clear the queue.
Inputs: game (required), limit, offset.
list_variablesARead-only
List a game's variables — the subcategories and filters a leaderboard accepts.
Each variable has an id and a values map of {value_id: label}. Pass these
to get_leaderboard/get_world_record as variables={variable_id: value_id}
to target a specific subcategory (e.g. '16 Star', difficulty 'Hard').
Inputs: game (required). Returns: result
search_gamesARead-only
Fuzzy-search games by name. Returns ids, abbreviations and release years.
Use the returned id (or abbreviation) with the other tools.
Inputs: name (required), limit, offset.
search_seriesARead-only
Fuzzy-search game series (e.g. 'Mario', 'Zelda') by name.
A series groups related games; pass a returned id to get_series to list
the games it contains.
Inputs: name (required), limit, offset.
search_usersARead-only
Search for speedrun.com users by name. Returns ids, countries and signup dates.
Inputs: name (required), limit, offset.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target a distinct resource/action such as games, categories, variables, leaderboards, users, runs, platforms, regions, and series. The main overlap is that get_game already returns categories and get_world_record is a wrapper over get_leaderboard, but the descriptions clarify when each should be used.
All tool names consistently follow a snake_case verb_noun pattern using only search, get, and list as verbs. Multiword nouns like get_user_personal_bests and get_game_records remain predictable and no mixed conventions appear.
Sixteen tools is slightly above the typical ideal range, but each tool covers a distinct read-only aspect of the speedrun.com API. The count feels reasonable for the domain, with only a few convenience helpers adding mild extra weight.
Core discovery and leaderboard workflows are well covered: searching games and users, retrieving game details, categories, variables, leaderboards, world records, runs, platforms, regions, and series. However, list_unverified_runs references verify_run/reject_run that are not included in the tool set, leaving a moderation dead end, and there is no direct user profile lookup beyond personal bests.
Maintenance
Related MCP Connectors
Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Enables AI assistants to natively interact with the Serpzilla link-building marketplace.
Query your SEO data in plain language: rankings, audits, backlinks, competitors and AI visibility.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to access World Cube Association speedcubing data including world records, competitor profiles, competition information, and championship results. Supports queries about rankings, competition schedules, and detailed speedcubing statistics through natural language.121MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to explore player profiles, ratings, game archives, leaderboards, clubs, and puzzles via the Chess.com API.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query Speedrun.com data through the official API, supporting tools for retrieving game, run, and leaderboard information.73 npmMIT
- AlicenseAqualityDmaintenanceEnables querying and managing RetroAchievements data, including user profiles, achievements, game info, and site rankings through natural language.131MIT