Osu! MCP. Pull player stats and map data instantly.
Gemini Works with every AI agent you already use
…and any MCP-compatible client
Just plug in your AI agents and start using Vinkius.
Osu! provides direct access to the Osu! API via your AI agent. It lets you query player profiles, look up beatmap details, calculate map difficulty with different mods, and browse community discussions—all without opening a browser tab.
You can check top scores, analyze user performance on specific maps, and manage favorite content right from your chat window.
What your AI agents can do
Get beatmap attributes
Retrieves technical details and modifiers for a specific beatmap file.
Get beatmap pack
Fetches data about an entire collection or bundle of beatmaps.
Get beatmap scores
Pulls the top leaderboard scores for a specific, given beatmap ID.
Retrieve detailed public data, including stats and rankings, for any authenticated Osu! user.
Find specific beatmap files or browse curated collections of maps by ID or name.
Adjust a map's perceived difficulty (stars, AR, BPM) based on applied mod combinations and rulesets.
Get a specific player's score against a known beatmap ID or check the top scores for that track.
Access and list beatmapsets marked as favorites by the user, or browse general beatmap packs.
Pull discussion posts and votes from a specific beatmapset to track community feedback on mapping decisions.
Ask AI about this MCP
Supported MCP Clients
Gemini Waiting for input…
Osu! MCP Server: 13 Tools for Scoring and Data Retrieval
Use these 13 tools to pull specific Osu! data points—from user ranks and beatmap attributes to community discussion votes—directly into your workflow.
019e5d41get beatmap attributes
Retrieves technical details and modifiers for a specific beatmap file.
019e5d41get beatmap pack
Fetches data about an entire collection or bundle of beatmaps.
019e5d41get beatmap scores
Pulls the top leaderboard scores for a specific, given beatmap ID.
019e5d41get beatmapset
Gets metadata and information about an entire collection of related maps.
019e5d41get favourites
Lists the IDs or names of beatmapsets that the user has marked as favorites.
019e5d41get me
Retrieves the calling user's personal profile data, including stats and ranking information.
019e5d41get user beatmap score
Calculates and returns a specific user's recorded score on a designated beatmap.
019e5d41list beatmap packs
Retrieves a list of all available general beatmap packs by name or category.
019e5d41list discussion posts
Gets the latest discussion threads and comments related to a specific beatmapset.
019e5d41list discussion votes
Retrieves aggregated votes cast on decisions or suggestions within a beatmapset's discussion.
019e5d41list discussions
Gets an overview of all general discussions attached to a specific beatmapset.
019e5d41lookup beatmap
Searches the database and returns fundamental metadata for a specific beatmap file ID.
019e5d41search beatmapsets
Performs a targeted search across all available beatmapset collections.
Choose How to Get Started
Build a custom MCP for your own tools, or connect a ready-made integration from our catalog.
Build Your Own
Turn any API into an MCP. Import a spec, define Agent Skills, or deploy with MCPFusion.
- Import from OpenAPI, Swagger, or YAML specs
- Create Agent Skills with progressive disclosure
- Deploy to edge with MCPFusion framework
- Built in DLP, auth, and compliance on every call
- Real time usage dashboard and cost metering
- Publish to catalog or keep private
Make Your AI Do More
Start with Osu!, then connect any of our 4,700+ other servers whenever your AI needs more. One click, no limits.
- Use this MCP plus 4,700+ others, all in one place
- Add new capabilities to your AI anytime you want
- Every connection is secured and compliant automatically
- Track usage and costs across all your servers
- Works with Claude, ChatGPT, Cursor, and more
- New servers added to the catalog every week
What you can do with this MCP connector
You connect your Osu! account right into this agent. You get direct access to the full Osu! API, so you're not stuck opening a browser tab just to check stats or find a map. This lets you query player profiles, look up beatmap details, calculate difficulty changes with mods, and even check out community discussions—all from your chat window.
Getting Your Stats & Checking Scores
You can instantly grab detailed public data about yourself using get_me, checking your global rank and total PP without leaving the conversation. If you wanna see what another player is rocking, you'll find ways to check their full profile details. When it comes to scores, you don't gotta guess: use get_user_beatmap_score to calculate a specific user's recorded score on any beatmap ID.
Need to know who the best players are? You can pull up the top leaderboard scores for any given map using get_beatmap_scores.
Finding and Analyzing Beatmaps
If you know exactly what you want, you can search the database with lookup_beatmap to get fundamental metadata on a specific beatmap file ID. For bigger finds, use search_beatmapsets or get_beatmapset to target entire collections of related maps. You can also browse general bundles using list_beatmap_packs, which gives you all available packs by name or category, or fetch data about a whole collection with get_beatmap_pack.
If you're checking out the mapsets you like best, get_favourites lists the beatmapsets you've marked as favorites. To see what’s in a single file, get_beatmap_attributes retrieves all the technical details and modifiers for that specific beatmap file.
Mapping Difficulty Changes
You don't just get base stats; you can run some math on 'em. You use get_beatmap_attributes to calculate how a map's perceived difficulty—the stars, AR, and BPM—changes when you apply different mod combinations or rulesets.
Tapping Into the Community Vibe
You wanna know what people are talking about? Use these tools. list_discussions gives you an overview of all general discussions attached to a specific mapset. You can then dig into specific threads using list_discussion_posts to get the latest posts and comments related to that mapset. If someone's making a decision on how the map should change, you'll find out what people think by running list_discussion_votes, which pulls aggregated votes cast on decisions or suggestions within that beatmapset’s discussion.
How Osu! MCP Works
- 1 First, subscribe to the Osu! server and provide your personal API access token.
- 2 Next, tell your AI agent what you need—for example, 'What are the top scores for beatmap X?'
- 3 The agent runs the necessary tool (like
get_beatmap_scores) through this server and returns the structured data to you.
The bottom line is: Your AI client talks directly to the Osu! API, fetching specific game data when prompted.
Who Is Osu! MCP For?
Competitive players who can't afford to context-switch are the primary users. Think about the high-level data analyst or content creator who needs stats and trends immediately. This is for anyone who uses Osu! but hates clicking through multiple web pages just to get a single number.
Checks current stats, compares their top scores against others using get_user_beatmap_score, and analyzes map difficulty with mods before practice.
Reviews community reception by listing discussion posts (list_discussion_posts) or checking general votes on a beatmapset to gauge feedback.
Extracts structured data like attribute changes using get_beatmap_attributes or retrieves historical scoring metrics for tracking performance over time.
What Changes When You Connect
- Check live scores against the leaderboard. Instead of checking a website, you just ask your agent to 'What are the top scores for beatmap ID 1234567?' using
get_beatmap_scores. You get the result in text format immediately. - Analyze map difficulty on the fly. Need to know what a map feels like with DoubleTime? Use
get_beatmap_attributesto calculate changes to AR and BPM without opening any external mod calculator tool. - Stay updated on community trends. Don't wade through forum threads. Use
list_discussion_postsorlist_discussionsto pull the latest feedback or votes from a beatmapset, giving you instant insight into mapping direction. - Manage your personal data easily. Want to know your ranking? Run
get_me. It pulls your full profile—PP, rank, accuracy—and gives it straight to your agent for use in other scripts. - Efficiently find resources. Instead of guessing a map's ID, you can run
search_beatmapsetsorlist_beatmap_packsto narrow down exactly what kind of content exists.
Real-World Use Cases
Comparing Rival Performance
You want to know if Player B is actually better than you on a specific map. You run get_user_beatmap_score for both of your IDs against the same beatmap ID and get two scores instantly, allowing direct comparison without switching tabs.
Mapping Research
You're designing a new map. You run get_beatmapset to check the existing metadata for similar maps, then use list_discussion_posts to see what mappers are arguing about in the community thread before you commit to your own design.
Pre-Game Warmup Check
Before a match, you need to know how much harder a map will feel with specific mods. You call get_beatmap_attributes and pass in the desired mod list; it returns the adjusted star count and BPM for your analysis.
Curating Content Lists
You need to build a playlist of maps for practice. You use get_favourites to pull all the beatmapsets you've saved, then run list_beatmap_packs to find related official packs, ensuring your list is comprehensive.
The Tradeoffs
Trying to search by name only
Asking the agent 'Show me all maps about rock music.' The API doesn't support fuzzy text searches on general topics.
→
You need to narrow it down. Use search_beatmapsets with known keywords or use a specific lookup tool like lookup_beatmap if you have an ID. Don't assume the agent can read your mind.
Confusing user data and map metadata
Asking 'What is my score on this beatmap?' but providing only a general discussion link. You need both specific identifiers to get results.
→
You must use get_user_beatmap_score and provide three things: your user ID, the target map ID, and the required scope. Never assume it knows which score you mean.
Ignoring mod math
Calculating difficulty manually using a web tool instead of checking for official changes.
→
Always run get_beatmap_attributes when you apply mods. It gives the accurate, server-side calculation for AR and BPM increases, which is necessary data.
When It Fits, When It Doesn't
Use this MCP Server if your core workflow involves reading structured Osu! API data: scores, stats, or map metadata. You need to check a number (e.g., 'What is my rank?', 'What are the top 50 scores?'). If you only want to read general text—like summarizing a discussion post without pulling specific votes (list_discussion_posts)—you might get away with simpler web scraping, but if you need accurate data points like PP, AR, or BPM changes, this server is mandatory. Don't use it if you just want basic info; always run lookup_beatmap first to confirm the map exists. If your goal is general API access for unrelated gaming services (like a different rhythm game), then skip this and look at other dedicated MCP servers.
Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Osu!. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.
VINKIUS INFRASTRUCTURE
Cloud Hosted
Managed infra
V8 Isolated
Sandboxed per request
Zero-Trust Proxy
No stored credentials
DLP Enforced
Policy on every call
GDPR Compliant
EU data residency
Token Compression
~60% cost reduction
Works with Claude, ChatGPT, Cursor, and more
The Model Context Protocol standardizes how applications expose capabilities to LLMs. Instead of operating in isolation, your AI gains direct access to external platforms, live data, and real-world actions through secure, standardized connections.
This server provides 13 capabilities that interface natively with Claude, ChatGPT, Cursor, and any MCP client. No middleware. No custom integration required.
Available Capabilities
Sifting through web pages for scores feels like pulling teeth.
Right now, if you want to compare your score on Map A against the top player's score on Map B, you open the Osu! site. You find Map A, check your performance tab (clicking 3 times). Then you close that and navigate to Map B’s leaderboard, scrolling until you find the high score. It takes context switching and copy-pasting just to get two numbers.
With this server, you tell your agent: 'Compare my best run on map X with the top player's score on map Y.' The agent runs `get_user_beatmap_score` and `get_beatmap_scores`, pulls both results into a single payload. You get the numbers instantly, right in your chat.
Osu! MCP Server: Get stats, scores, and data.
Previously, analyzing map difficulty meant opening external mod calculators or relying on community wiki pages. You'd have to manually input the base star count, then input 'DoubleTime,' and hope the calculation was correct. It’s a messy process with no single source of truth.
Now, you ask your agent: 'What happens if I apply DoubleTime to beatmap 987654?' The server runs `get_beatmap_attributes`, gives you the precise star increase, and provides the corrected AR and BPM. You don't calculate it; the data does.
Common Questions About Osu! MCP
How do I get my own player profile using the Osu! MCP Server? +
You run the get_me tool. It needs your identify scope permissions, but it pulls all the basic public data for you: your current rank and total PP score.
What is the difference between `lookup_beatmap` and `search_beatmapsets`? +
lookup_beatmap gives you metadata for a single, specific file (a map). search_beatmapsets finds entire collections or groupings of maps by keyword.
Can I calculate difficulty using the Osu! MCP Server? +
Yes. You use get_beatmap_attributes. Just pass in the map ID and the mod names (e.g., 'DoubleTime') to get the modified star rating.
Where do I find top scores for a beatmap? +
Use the get_beatmap_scores tool. You just need to provide the specific ID of the map you want the leaderboard for, and it returns the current top results.
What authentication method does the Osu! MCP Server use when calling tools like `get_user_beatmap_score`? +
It requires an Osu! Personal Access Token (PAT). You must provide this token during server setup for any tool that accesses user-specific data, ensuring your AI client can authenticate on your behalf.
How do I use `list_discussion_posts` or `list_discussion_votes` to track community feedback? +
These tools pull the discussion threads and vote counts associated with a beatmapset. You can feed this data into your AI agent for analysis, letting it summarize current mapping trends or highlight controversial points.
What does the tool `get_favourites` retrieve, and what is its purpose? +
This tool fetches a list of beatmapsets you have marked as favorites. It's useful for quickly reviewing content you intend to play again without manually checking your profile.
If I use `lookup_beatmap` with an invalid ID, what should I expect? +
The API handles invalid or nonexistent IDs by returning a structured error response. Your AI client can read this specific error code to confirm the beatmap doesn't exist before attempting further actions.
Can I calculate the difficulty of a beatmap with specific mods like DoubleTime or HardRock? +
Yes! Use the get_beatmap_attributes tool. You can provide the Beatmap ID and an array of mods to get the adjusted difficulty metrics like Star Rating, AR, and OD.
How do I find my own profile statistics? +
Simply run the get_me tool. It will return your public profile data, including your global rank, PP, and accuracy for your primary ruleset.
Is it possible to search for new beatmapsets by a specific artist? +
Yes, use the search_beatmapsets tool with a query string. For example, searching for 'Camellia' will return all relevant beatmapsets associated with that artist.
Use it with your favorite AI tools
Connect this server to Cursor, Claude, VS Code, and more.
More in this category
Play.ht (Voice Cloning)
Generate ultra-realistic speech and clone voices instantly using Play.ht's advanced AI voice engines directly from your agent.
Musixmatch Alternative
Access the world's largest lyrics database — search tracks, retrieve synchronized subtitles, and explore global music charts directly from your AI agent.
Cartesia (Voice AI)
Generate lifelike AI voices, clone speech, and transcribe audio with Cartesia's state-of-the-art Sonic models directly from your AI agent.
You might also like
Raven Tools
Track SEO rankings, audit website health, and generate white-label marketing reports for your clients automatically.
OpenTHC
Automate cannabis compliance via OpenTHC — track plants, manage inventory, query lab results, and handle B2B/B2C transactions directly from any AI agent.
Prisma Access
Connect Prisma Access to any AI agent via MCP.