osu-mcp

PyPI Tests Coverage License: MIT

osu-mcp is a Model Context Protocol (MCP) server that exposes the osu! API v2 as tools for Claude Desktop and other MCP clients. Ask Claude about your osu! profile, compare players, search beatmaps, browse rankings — all in natural language.

Quickstart

1. Install

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

2. Get osu! API credentials

1. Go to https://osu.ppy.sh/home/account/edit
2. Scroll to OAuth, click New OAuth Application
3. Name: anything (e.g., "Claude Desktop"); Callback URL: leave blank.
4. Copy the Client ID and Client Secret.

3. Configure credentials

Option A — environment variables (recommended):

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

Option B — config file at ~/.config/osu-mcp/config.toml (Linux/Mac) or %APPDATA%\osu-mcp\config.toml (Windows):

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

4. Wire up Claude Desktop

Add to claude_desktop_config.json:

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

Restart Claude Desktop. You should see "osu" in the MCP servers list.

Available tools (12)

Tool	Description
get_user_summary	Profile + stats; optionally embed recent/best/firsts scores
compare_users	Side-by-side comparison of 2-5 users
get_user_scores	List a user's best/recent/firsts scores
get_score_details	Full attributes of a specific score
search_beatmaps	Search beatmapsets with filters (mode, status, difficulty, length, BPM)
get_beatmap_details	Full attributes of a beatmap (AR/OD/CS/HP, BPM, max combo)
get_beatmap_scores	Top scores on a beatmap, filterable by mods
get_beatmapset	Full beatmapset with all difficulties
get_rankings	pp/score/charts rankings, global or by country
get_country_top	Top N players of a country in pp ranking
get_news_posts	Recent osu! news posts
get_seasonal_backgrounds	Active seasonal backgrounds

Full reference: docs/tools.md.

Examples

In Claude Desktop, try:

"Show me peppy's osu! stats"

"Compare Cookiezi and WhiteCat on accuracy and pp"

"What are the top 10 osu! players from Ecuador?"

"Find me some 200 BPM streamy ranked maps"

Development

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/

License

MIT — see LICENSE.