osu-mcp: An MCP Server That Lets Claude Analyze Your osu! Stats in Plain English

osu-mcp is an MCP server that lets Claude Desktop (or any MCP client) talk to the osu! API v2. It's now published on the official MCP Registry as io.github.Osyanne/osu-mcp. The repo is github.com/Osyanne/osu-mcp and the PyPI package is osu-mcp (MIT license, PRs welcome).

What It Does — 12 Tools

• Player profiles + score history (best / recent / #1s)
• Beatmap search with filters (BPM, difficulty, length, status)
• Global + country pp rankings
• Per-map leaderboards, filterable by mods
• News posts + seasonal backgrounds

Real Demo on the Author's Account

Claude was asked: "Show me my top 10 plays and then compare me with the top 5 players from Ecuador."

Claude pulled the top plays (e.g., 208.88 pp Dear My Friend DT, 206.33 pp happy*lucky DT), fetched the EC country leaderboard, and computed pp-per-play efficiency across all three players. The insight: the author's accuracy (98.18%) is identical to the #1 player in Ecuador — the gap is volume, not skill. A calculation the author says they'd never have done manually.

Setup Instructions

uv tool install osu-mcp

Create an OAuth app at https://osu.ppy.sh/home/account/edit (click "New OAuth Application", leave callback blank), then add to claude_desktop_config.json:

"osu": {
  "command": "uvx",
  "args": ["osu-mcp"],
  "env": { "OSU_CLIENT_ID": "...", "OSU_CLIENT_SECRET": "..." }
}

Restart Claude. Done.

Who It's For

osu! players and data analysts who want AI-assisted breakdowns of their performance without digging through API responses manually.