speedrun.com

⏱️ 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" } }

Tools

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 # equivalent

Use 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-mcp

One-click install in Claude Desktop

Each GitHub release ships a speedrun-mcp- .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:

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

1. Log in to speedrun.com.
2. Go to your account settings.
3. In the left-hand nav, find the Developers section and click API Key.
4. 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 tools

Keep 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-mcp

Supporting 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 submissio