speedrun.com

⏱️ speedrun-mcp

speedrun.com 向けの Model Context Protocol サーバーです。AI アシスタントからゲーム、カテゴリ、リーダーボード、世界記録、プレイヤーとその自己ベストを検索でき、（API キーがあれば）記録の申請や審査も行えます。

「Super Mario 64 の 16-star の現在の世界記録は何秒で、保持者は誰ですか？」

speedrun.com の公式 REST API を基盤にしています。読み取りツールの利用にアカウントや API キーは不要です。API キーを追加すると（認証が必要な機能を参照）、ユーザー情報の読み取りが利用可能になり、必要に応じて記録の申請や審査も行えます。speedrun.com は広告収入で運営されており、API の読み取りでは広告が表示されないため、サポーターでない場合、サーバーはアシスタントにサポータープログラムについて時折案内するよう求めます。結果は、モデルが扱いやすいコンパクトな JSON で返されます（プレイヤー ID は名前に変換され、時間は書式化され、サブカテゴリの変数にはラベルが付けられます）。

例

*「SM64 の 16-star の世界記録は？」*と尋ねると、モデルは 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 位の記録と、同率 1 位の記録
get_game_records	1 回の呼び出しで、ゲームの全カテゴリの記録を取得（デフォルトでは世界記録）
search_series	ゲームシリーズをあいまい検索（例：Mario、Zelda）
get_series	シリーズの詳細と、含まれるゲーム
search_users	ユーザー名でプレイヤーを検索（一部一致、あいまい一致）
get_user_personal_bests	プレイヤーの全ゲームにわたる自己ベスト
get_run	1 件の記録の詳細
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 リリース には、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キーは空欄で、書き込みは無効になっています。.envはGitによって無視されます。

サーバーはエクスポートされた環境変数を読み取り、.envを自動では読み込みません。ローカルファイルを読み込んでシェルからサーバーを起動するには、次のようにします。

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

speedrun.com を支援する

speedrun.com はコミュニティによって運営され、ページに表示される広告によって運営費が賄われています。 公開 API には広告がないため、このサーバーが返す回答はすべて、サイトに報酬が支払われないページビューとなります。このプロジェクトが存在するのは、リーダーボード、モデレーション、そして記録そのものがコミュニティによって支えられているからです。データにアクセスしやすくすることで、そのコミュニティに気づかれないまま負担をかけるべきではありません。

そのため、このサーバーはその点について一つの対応をしています。すでにサイトを支援していると確認できない場合、アシスタントにそのことを伝えるよう促します。

• サーバーセッションの最初の結果と、その後3回ごとの結果には、短い supporter_notice が含まれます。これは、API の読み取りでは広告が表示されないことを説明し、サイトの運営資金となるサポータープログラムを案内します。サポータープログラムでは、広告なしの閲覧やその他の特典を利用できます。
• サーバーの指示では、アシスタントにその内容を一文で伝えるよう求めています。実際に伝えるかどうかはアシスタント次第ですが、通常は最初に表示された際に触れ、その後も触れることがあります。

この通知が表示されるのは、API キーがない場合、またはキーのアカウントがサポーターではない場合だけです。キーを追加したサポーターには表示されません。すでに閲覧中のサイトを支援しているためです。whoami は、検出されたステータスを supporter として報告します。照会自体に失敗した場合（サイトの非公開 v2 API を使用します）、サーバーは何も仮定せず、すでに支払いをしているかもしれない人にしつこく勧めないよう、通知を控えます。

利用制限はありません。これまでどおり、すべての読み取りツールはキーなしで動作します。このサーバーを通じて speedrun.com の恩恵を受ける人に、何らかの形で還元する方法を知ってもらうことが目的です。

注意事項と制限

• 読み取りにキーは不要です。書き込みはオプトインです。 リーダーボード、ゲーム、プレイヤー、モデレーションキューは、制限なく読み取れます。ランの提出とモデレーションには、SPEEDRUN_API_KEY と SPEEDRUN_ENABLE_WRITES が必要です（上記を参照）。
• レート制限： speedrun.com では、IP ごとに1分あたり100件のリクエストが許可されます。超過すると HTTP 420 が返されます。上限に達すると、クライアントはわかりやすいエラーを表示します。
• ゲームとカテゴリの引数には、ID（o1y9wo6q）または略称（sm64）を指定できます。正確なサブカテゴリのリーダーボード（例：16 Star）を取得するには、list_variables で変数 ID と値 ID を調べ、variables={variable_id: value_id} を渡してください。
• エラーの内容はわかりやすく表示されます。 無効な ID やフィルターを指定すると、speedrun.com 独自のメッセージを含むエラーが発生します。たとえば、フルゲームカテゴリに level を渡すと、「選択されたカテゴリはフルゲームラン用ですが、レベルが選択されています。」 と返されます。

出力形式

• タイムには、リーダーボードの並べ替えに使われる計測方式が反映されます。timing（realtime / realtime_noloads / ingame）を渡すと、報告される time / time_seconds はゲームのデフォルトの計測方式ではなく、そのランキングに対応する値になります。
• get_leaderboard は、returned_runs（返されたランの数。top と同着による制限を受け、リーダーボード全体の件数ではありません）と、解決済みのプレイヤー名、フォーマット済みのタイム、ラベル付きのサブカテゴリを含む runs リストを返します。
• get_world_record は、world_record（1位のラン。リーダーボードが空の場合は null）と、1位に同着した他のランがあればその一覧 tied を返します。
• 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 には、network マーカーで選択される実際の API チェックがあります。

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 registry に新しいバージョンを公開します。レジストリには PyPI パッケージとバンドルの両方が掲載されます。レジストリ認証には GitHub OIDC を使用するため、トークンは保存されません。PyPI は、この README の先頭にある mcp-name コメントを通じて所有権を確認します。

Ruff は、よくあるバグ、セキュリティ上の問題、非同期処理の誤り、複雑すぎる関数、pytest の誤りについて、ソースコードとテストをチェックします。また、インポートの並べ替えと Python コードのフォーマットも行います。テストでは assert を使用できますが、それ以外の lint ルールはソースコードとテストの両方に適用されます。サーバーは MCP プロトコルに stdout を使用するため、print 文とデバッガー文は許可されません。

Ruff のバージョンは、開発用依存関係、required-version 設定、pre-commit で同じものに固定されています。3 つすべてをまとめて更新してください。フックは安全な lint 修正とフォーマットを適用してから mypy を実行します。CI ではファイルを変更せずにチェックします。

ライセンス

MIT