osu! MCP
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.
- tools
- 12
- auth
- Secret needed
- transport
- STDIO
- env vars
- 2
- last updated
- May 23, 2026
Tools
12 toolsPublic tool metadata for what this MCP can expose to an agent.
get_user_summaryProfile + stats; optionally embed recent/best/firsts scores
Profile + stats; optionally embed recent/best/firsts scores
No parameter schema in public metadata yet.
compare_usersSide-by-side comparison of 2-5 users
Side-by-side comparison of 2-5 users
No parameter schema in public metadata yet.
get_user_scoresList a user's best/recent/firsts scores
List a user's best/recent/firsts scores
No parameter schema in public metadata yet.
get_score_detailsFull attributes of a specific score
Full attributes of a specific score
No parameter schema in public metadata yet.
search_beatmapsSearch beatmapsets with filters (mode, status, difficulty, length, BPM)
Search beatmapsets with filters (mode, status, difficulty, length, BPM)
No parameter schema in public metadata yet.
get_beatmap_detailsFull attributes of a beatmap (AR/OD/CS/HP, BPM, max combo)
Full attributes of a beatmap (AR/OD/CS/HP, BPM, max combo)
No parameter schema in public metadata yet.
get_beatmap_scoresTop scores on a beatmap, filterable by mods
Top scores on a beatmap, filterable by mods
No parameter schema in public metadata yet.
get_beatmapsetFull beatmapset with all difficulties
Full beatmapset with all difficulties
No parameter schema in public metadata yet.
get_rankingspp/score/charts rankings, global or by country
pp/score/charts rankings, global or by country
No parameter schema in public metadata yet.
get_country_topTop N players of a country in pp ranking
Top N players of a country in pp ranking
No parameter schema in public metadata yet.
get_news_postsRecent osu! news posts
Recent osu! news posts
No parameter schema in public metadata yet.
get_seasonal_backgroundsActive seasonal backgrounds
Active seasonal backgrounds
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageConfiguration
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.
Readme
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
Details
- Repository
- github.com/osyanne/osu-mcp
- Category
- Search & Web Crawling
- Package
osu-mcp- Transport
- STDIO
- Auth
- Required
- Registry
- MCP registry, active
Related Search & Web Crawling MCP servers
View all
Calendar.appp-l-ta/calendar-mcpList, search, and manage calendar events via macOS Calendar.app across all configured accounts.0stars
prxhubparallect/prxhubSearch, cite, download, and publish .prx research bundles on prxhub.com.0stars
PartsTablecom.partstable/partstableCalibrated IT hardware parts reference: PN normalization, search, cross-references, cited facts.0stars
Agentlookup Mcppeureka/agentlookup-mcpSearch, discover, and register AI agents in the public registry at agentlookup.dev.0stars
POS.DO MCP Serverposdo-io/mcp-serverDiscover 356K+ restaurants in 20 countries: search, reviews, cultural context, time-based offers.0stars
Prospeo Mcp Serverprospeo-v2/prospeo-mcp-serverProspeo: Find, search, and enrich people and companies with verified emails and mobile numbers.0stars