# Osu! MCP for AI Agents AI Agent Connect

> Osu! MCP connects your AI agent to the Osu! API to pull player stats, beatmap data, and community feedback. It lets you query rankings, search for specific maps, and check discussion trends without leaving your chat or workspace. Use it to analyze map difficulty or browse curated beatmap packs instantly.

## Overview
- **Category:** audio-music
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_idbAvUACFPzs9KS850RTtZmf4Xh5bSzXK57yhZpw/ai-agent-connect
- **Tags:** rhythm-game, beatmaps, osu-api, player-stats, leaderboards

## Description

Imagine you're deep into a rhythm game project or just trying to keep tabs on your personal progress. Instead of jumping between browser tabs to check your global rank, look up a beatmap's difficulty with specific mods, or see what the community is saying about a new pack, you can just ask your agent. This Connector handles the heavy lifting of talking to the Osu! API v2 for you. You can pull up your own profile stats instantly or dig into the specifics of a map's scoring. If you're a mapper, you can see how people are voting on your work or what the general sentiment is in the discussion threads. It turns your AI into a research assistant for the rhythm game ecosystem. Because Vinkius makes it so easy to connect these tools, you can swap between different data sources quickly, but this specific connection is your direct line to everything Osu! has to offer. It's about getting answers without the friction of manual searching. You can get a clear picture of how a map performs under different rulesets or find exactly what a specific user likes without hunting through menus. It takes the guesswork out of data collection for your favorite rhythm game.

## Tools

### get_beatmap_pack
Retrieves a specific beatmap pack. Use this when you need to grab a whole collection at once.

### list_beatmap_packs
Shows all available beatmap packs. This is great for browsing curated content.

### get_beatmap_scores
Gets the scores for a specific beatmap. It lets you see how others performed on a map.

### get_beatmapset
Pulls information for a specific beatmapset. Use this to get the core details of a map collection.

### list_discussion_votes
Shows the votes for a beatmapset discussion. It helps you see what the community likes.

### list_discussions
Pulls the discussion threads for a beatmapset. This lets you see what people are actually saying.

### get_favourites
Retrieves the beatmapset favorites for a user. Use this to see what a specific player likes.

### lookup_beatmap
Finds a specific beatmap based on its ID. It's the quickest way to get data on a single map.

### get_user_beatmap_score
Pulls a specific user's score on a map. This is perfect for checking your own personal bests.

### get_beatmap_attributes
Pulls specific details about a beatmap. It helps you see the underlying data for any map.

### get_me
Pulls the authenticated user's data. This is how your agent knows who you are.

### search_beatmapsets
Searches for beatmapsets across the game. Use this to find new content quickly.

### list_discussion_posts
Lists all posts within a beatmapset discussion. This helps you read through the whole community thread.

## Prompt Examples

**Prompt:** 
```
What's my current rank and how many PP do I have?
```

**Response:** 
```
I've pulled your current profile data:

*   **Global Rank:** #12,450
*   **Performance Points:** 5,200 PP
*   **Accuracy:** 98.5%

Would you like to see your top performances on specific maps?
```

**Prompt:** 
```
Check the top scores for beatmap 123456.
```

**Response:** 
```
Here are the top scores for beatmap 123456:

| Rank | Player | Score | Mods |
| :--- | :--- | :--- | :--- |
| 1 | PlayerOne | 1,200,340 | Hidden+HardRock |
| 2 | RhythmQueen | 1,150,000 | Hidden |
| 3 | BeatMaster | 1,120,000 | HardRock |

Let me know if you want to see more entries.
```

**Prompt:** 
```
How does DoubleTime change the difficulty of beatmap 987654?
```

**Response:** 
```
With the **DoubleTime** mod applied to beatmap 987654:

*   **Base Difficulty:** 5.2 Stars
*   **Modified Difficulty:** 7.4 Stars
*   **New Approach Rate (AR):** 10.3
*   **New BPM:** 270

It significantly increases the speed and complexity of the map.
```

## Capabilities

### Pull player profiles
Get your own stats and global ranking in seconds.

### Search beatmaps
Find specific maps or curated packs by ID or hash.

### Check scores
Look up top leaderboard entries for any given beatmap.

### Analyze difficulty
See how different mods and rulesets change a map's star rating.

### Read discussions
Access community posts and votes to gauge public opinion.

### Fetch favorites
See which beatmapset favorites are currently favorited by a user.

## Use Cases

### Checking personal bests
A player wants to see their score on a specific map. They ask the agent to check their score using get_user_beatmap_score.

### Mapping feedback
A mapper wants to see why a map is getting downvotes. They ask the agent to pull discussion posts with list_discussion_posts.

### Difficulty checking
A player wants to know how hard a map is with DoubleTime. The agent uses get_beatmap_attributes to calculate the new rating.

### Content discovery
A user wants to find new packs. The agent uses list_beatmap_packs to show the latest curated collections.

## Benefits

- Get your ranking and stats instantly. Use get_me to let your agent know your current standing without opening the game client.
- Analyze map difficulty with precision. Use get_beatmap_attributes to see how different mods change the star rating.
- Monitor community sentiment. Use list_discussion_votes and list_discussions to see what mappers and players are saying.
- Track your best performances. Use get_user_beatmap_score to quickly check your personal bests on any specific map.
- Browse curated content easily. Use list_beatmap_packs to find new music and community-made collections in one go.

## How It Works

The bottom line is you get direct API access to Osu! data through a simple chat interface.

1. Subscribe to the Osu! MCP on Vinkius.
2. Provide your Osu! Personal Access Token in the configuration.
3. Ask your agent to fetch your stats or search for specific beatmaps.

## Frequently Asked Questions

**Can the Osu! MCP show my personal ranking?**
Yes, it pulls your public stats from the Osu! API so your agent can tell you your current rank, PP, and accuracy instantly.

**Can I use Osu! MCP to see community feedback?**
Yes, it can pull discussion threads and votes for specific beatmapsets, allowing you to see what the community thinks of a map.

**Does Osu! MCP work with Cursor?**
Yes, it works with any MCP-compatible client, including Cursor, Claude, and Windsurf.

**Can I check scores for specific maps?**
Yes, you can ask your agent to fetch the top leaderboard scores for any beatmap ID.

**Can Osu! MCP find beatmap packs?**
Yes, it can list available beatmap packs and retrieve specific ones for you to explore.

**How do I get my own data with Osu! MCP?**
Once connected, your agent can use the get_me tool to pull your specific profile data using your personal access token.

**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.