Summary
Exposes the osu! API v2 so you can query player profiles, compare stats, search beatmaps, and pull rankings directly through Claude. Ships with twelve tools covering user summaries with embedded scores, side-by-side comparisons of up to five players, beatmap search with filters for difficulty, BPM, and length, and leaderboard data filterable by country or game mode. You'll need OAuth credentials from your osu! account settings, then wire them into Claude Desktop via environment variables or a config file. Useful if you're analyzing gameplay data, building training sets around rhythm game performance, or just want to ask Claude who holds the top score on a specific map without opening a browser.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
osu-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.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
OSU_CLIENT_ID*Numeric Client ID from your osu! OAuth application (https://osu.ppy.sh/home/account/edit).
OSU_CLIENT_SECRET*secretClient Secret from the same osu! OAuth application.
Categories
Registryactive
Packageosu-mcp
TransportSTDIO
AuthRequired
UpdatedMay 23, 2026
