About osu! MCP
osu! MCP is an MCP server for osu! API v2, aimed at players and analysts using Claude Desktop or other MCP clients. It provides tools for player and score data, beatmap discovery, rankings, and osu! news.
Key features
- 01Player profiles and statistics
- 02Compare 2–5 players
- 03Browse scores and beatmaps
- 04Global and country rankings
- 05Read news and seasonal backgrounds
Use cases
- 01Review a player's stats and scores
- 02Compare player performance
- 03Find beatmaps by BPM or difficulty
- 04Check top players by country
MCP support
Exposes osu! API v2 data and actions as tools for Claude Desktop and other MCP clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx osu-mcpOSU_CLIENT_IDNumeric Client ID from your osu! OAuth application (https://osu.ppy.sh/home/account/edit).OSU_CLIENT_SECRETSecretClient Secret from the same osu! OAuth application.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEosu-mcp
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
- Go to https://osu.ppy.sh/home/account/edit
- Scroll to OAuth, click New OAuth Application
- Name: anything (e.g., "Claude Desktop"); Callback URL: leave blank.
- 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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.