osu! MCP

osu-mcp

osu-mcp は、osu! API v2 を Claude Desktop やその他の MCP クライアント向けのツールとして公開する Model Context Protocol（MCP）サーバーです。Claude に osu! のプロフィールについて質問したり、プレイヤーを比較したり、ビートマップを検索したり、ランキングを閲覧したりできます。すべて自然言語で操作できます。

クイックスタート

1. インストール

uv tool install osu-mcp
# or
pip install osu-mcp

2. osu! API の認証情報を取得

1. https://osu.ppy.sh/home/account/edit にアクセスします
2. OAuth までスクロールし、New OAuth Application をクリックします
3. 名前：任意（例：「Claude Desktop」）。コールバック URL：空欄のままにします。
4. Client ID と Client Secret をコピーします。

3. 認証情報を設定

オプション A — 環境変数（推奨）：

export OSU_CLIENT_ID=12345
export OSU_CLIENT_SECRET=your-client-secret

オプション B — 設定ファイル（Linux/Mac の場合は ~/.config/osu-mcp/config.toml、Windows の場合は %APPDATA%\osu-mcp\config.toml）：

client_id = 12345
client_secret = "your-client-secret"

4. Claude Desktop に接続

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "osu": {
      "command": "uvx",
      "args": ["osu-mcp"],
      "env": {
        "OSU_CLIENT_ID": "12345",
        "OSU_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Desktop を再起動します。MCP サーバーの一覧に「osu」が表示されます。

利用可能なツール（12）

ツール	説明
get_user_summary	プロフィールと統計。最近のスコア、ベストスコア、初スコアを任意で含められます
compare_users	2～5 人のユーザーを並べて比較します
get_user_scores	ユーザーのベストスコア、最近のスコア、初スコアの一覧を取得します
get_score_details	特定のスコアの詳細な属性を取得します
search_beatmaps	フィルター（モード、ステータス、難易度、長さ、BPM）を指定してビートマップセットを検索します
get_beatmap_details	ビートマップの詳細な属性（AR/OD/CS/HP、BPM、最大コンボ）を取得します
get_beatmap_scores	ビートマップの上位スコアを取得します。MOD で絞り込めます
get_beatmapset	すべての難易度を含むビートマップセット全体を取得します
get_rankings	pp／スコア／チャートのランキングを取得します。全世界または国別に指定できます
get_country_top	pp ランキングにおける、ある国の上位 N 人のプレイヤーを取得します
get_news_posts	osu! の最新ニュース記事を取得します
get_seasonal_backgrounds	現在有効な季節の背景を取得します

完全なリファレンス：docs/tools.md。

使用例

Claude Desktop で、次のように試してみてください：

「peppy の osu! の統計を見せて」

「精度と pp で Cookiezi と WhiteCat を比較して」

「エクアドルの osu! プレイヤー上位 10 人は？」

「BPM 200 前後で、ストリーム系のランク付きマップを探して」

開発

git clone https://github.com/Osyanne/osu-mcp.git
cd osu-mcp
uv sync
uv run pytest                      # unit + smoke
uv run pytest -m integration       # integration (needs real creds)
uv run ruff check .
uv run mypy --strict src/

ライセンス

MIT — LICENSE を参照してください。