speedrun-mcp

# ⏱️ speedrun-mcp

<!-- mcp-name: io.github.williamcodes/speedrun-mcp -->

[![PyPI version](https://img.shields.io/pypi/v/speedrun-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/speedrun-mcp/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://pypi.org/project/speedrun-mcp/)
[![CI](https://github.com/williamcodes/speedrun-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/williamcodes/speedrun-mcp/actions/workflows/ci.yml)
[![MCP registry](https://img.shields.io/badge/MCP-registry-0098FF)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server for
[speedrun.com](https://www.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](https://github.com/speedruncomorg/api).
**The read tools need no account or API key** — add a key (see
[Authenticated features](#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](#supporting-speedruncom) 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:

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

## Tools

| Tool | What it does |
| --- | --- |
| `search_games` | Fuzzy-search games by name → ids & abbreviations |
| `get_game` | A game's details plus its categories (and optionally levels) |
| `list_categories` | A game's categories (`Any%`, `120 Star`, …) with rules |
| `list_variables` | Subcategory/filter variables and their value ids |
| `list_platforms` / `list_regions` | Platform / region ids for the `platform`/`region` leaderboard filters |
| `get_leaderboard` | A ranked leaderboard (top N; filter by variable / platform / region / timing) |
| `get_world_record` | The current #1 run for a game/category, plus any runs tied for first |
| `get_game_records` | Every category's records for a game in one call (defaults to world records) |
| `search_series` | Fuzzy-search game series (e.g. `Mario`, `Zelda`) |
| `get_series` | A series' details and the games it contains |
| `search_users` | Find players by username (partial, fuzzy match) |
| `get_user_personal_bests` | A player's PBs across all games |
| `get_run` | Details of a single run |
| `list_runs` | Runs filtered by player / game / category / status / examiner |
| `list_unverified_runs` | A game's runs awaiting verification (the moderation queue) |
| `whoami` | The profile that owns your API key *(only shown when a key is set)* |
| `list_notifications` | 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+.

```bash
# 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:

```bash
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`):

```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:

```bash
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](https://github.com/williamcodes/speedrun-mcp/releases)
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 |
| --- | --- |
| `SPEEDRUN_API_KEY` | Puts the server in **read-only authenticated mode**. Adds the identity reads — `whoami` (the profile your key belongs to) and `list_notifications`. The write tools (`submit_run`, `verify_run`, `reject_run`, `set_run_players`, `delete_run`) also become *visible*, but stay disabled — calling one returns a message telling you to enable writes. Until a key is set, none of these are advertised at all. |
| `SPEEDRUN_ENABLE_WRITES=1` | Switches to **read-write mode**: arms the write tools so they actually submit/moderate. Requires `SPEEDRUN_API_KEY` (moderation also needs a moderator key). Off by default — submitting and rejecting/deleting are real, permanent actions on real leaderboards, so opt in deliberately. |

**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](https://www.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.

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

Or with Claude Code:

```bash
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](.env.example) to `.env` and fill in the settings you need.
The template leaves the API key empty and disables writes. Git ignores `.env`