# Osu! MCP

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

## Overview
- **Category:** audio-music
- **Price:** Free
- **Tags:** rhythm-game, beatmaps, osu-api, player-stats, leaderboards

## Description

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.

## Tools

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

### list_beatmap_packs
Retrieves a list of all available general beatmap packs by name or category.

### get_beatmap_scores
Pulls the top leaderboard scores for a specific, given beatmap ID.

### get_beatmapset
Gets metadata and information about an entire collection of related maps.

### list_discussion_posts
Gets the latest discussion threads and comments related to a specific beatmapset.

### list_discussion_votes
Retrieves aggregated votes cast on decisions or suggestions within a beatmapset's discussion.

### list_discussions
Gets an overview of all general discussions attached to a specific beatmapset.

### get_favourites
Lists the IDs or names of beatmapsets that the user has marked as favorites.

### lookup_beatmap
Searches the database and returns fundamental metadata for a specific beatmap file ID.

### get_me
Retrieves the calling user's personal profile data, including stats and ranking information.

### search_beatmapsets
Performs a targeted search across all available beatmapset collections.

### get_user_beatmap_score
Calculates and returns a specific user's recorded score on a designated beatmap.

## Prompt Examples

**Prompt:** 
```
Show me my Osu! profile and current rankings.
```

**Response:** 
```
I've retrieved your profile. You are currently Rank #12,450 globally with 5,200 PP and 98.5% accuracy. Would you like to see your top performances?
```

**Prompt:** 
```
What are the top scores for beatmap ID 1234567?
```

**Response:** 
```
Fetching the leaderboard for beatmap 1234567... The #1 score is held by 'PlayerOne' with 1,200,340 points and a 99.8% Hidden+HardRock run.
```

**Prompt:** 
```
Calculate the difficulty of beatmap 987654 with DoubleTime.
```

**Response:** 
```
With DoubleTime applied, beatmap 987654 increases from 5.2 stars to 7.4 stars. The Approach Rate (AR) is now 10.3 and the BPM has increased to 270.
```

## Capabilities

### Fetch User Profiles
Retrieve detailed public data, including stats and rankings, for any authenticated Osu! user.

### Search and Retrieve Beatmaps
Find specific beatmap files or browse curated collections of maps by ID or name.

### Calculate Map Difficulty Changes
Adjust a map's perceived difficulty (stars, AR, BPM) based on applied mod combinations and rulesets.

### Check User Scores
Get a specific player's score against a known beatmap ID or check the top scores for that track.

### Manage Favorites & Packs
Access and list beatmapsets marked as favorites by the user, or browse general beatmap packs.

### Review Community Feedback
Pull discussion posts and votes from a specific beatmapset to track community feedback on mapping decisions.

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

## Benefits

- 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_attributes` to 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_posts` or `list_discussions` to 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_beatmapsets` or `list_beatmap_packs` to narrow down exactly what kind of content exists.

## How It Works

The bottom line is: Your AI client talks directly to the Osu! API, fetching specific game data when prompted.

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.

## Frequently Asked Questions

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