CategoryWeightCategory scoreContribution
Securityprompt, exec, net, exfil, eval
35%
35.0 pts
Supply chainhash, typosquat, maintainer, lockfile
20%
20.0 pts
Maintenancestaleness, pinning, CI
15%
15.0 pts
TransparencySKILL.md, perms, README
15%
15.0 pts
Communityinstalls, verify, response
15%
15.0 pts
Findings & checks · 0 flagged
Security
✓—All security checks passedNo findings in this category for the latest scan.pass
Supply chain
✓—All supply chain checks passedNo findings in this category for the latest scan.pass
Maintenance
✓—All maintenance checks passedNo findings in this category for the latest scan.pass
Transparency
✓—All transparency checks passedNo findings in this category for the latest scan.pass
Community
✓—All community checks passedNo findings in this category for the latest scan.pass
Every scanned point with the score it earned and what moved between them.
5ffcf1b
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<!-- mcp-name: io.github.Osyanne/osu-mcp -->
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-mcp2. 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-secretOption 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.