• DIFFICULTY
  • PERFORMANCE
  • MAP DATA
  • HUMAN

How to analyze beatmap difficulty and scores with your AI

Connect your agent to osu! to pull map data and player performance metrics instantly.

Ask AI about this page

Short answer

How can I use AI to analyze osu! maps and scores?

Your agent pulls map attributes and player scores to calculate difficulty adjustments and compare performance. You get specific data on star ratings and leaderboard rankings for any map you specify.

Data outcomes

What your agent produces

The specific data points your agent extracts from osu!.

DIFFICULTY

Adjusted star ratings

The AI uses map attributes to calculate how mods like Hard Rock or Double Time change the difficulty.

PERFORMANCE

Score comparisons

Compare specific player scores on a map to see how they stack up against the leaderboard.

MAP DATA

Beatmap details

Get technical metadata for any map, including length, BPM, and creator info.

HUMAN

Manual review

You decide which players or maps are worth deep-diving into based on the AI's summary.

The workflow

What your AI does when the request arrives.

The agent follows a sequence to turn a map ID into a full analysis.

  1. Locate the map

    The agent finds the specific beatmap you're interested in using its ID or search terms.

    lookup_beatmap

  2. Extract metadata

    It pulls the core difficulty settings and technical attributes of the map.

    get_beatmap_attributes

  3. Fetch rankings

    The agent pulls the top scores from the map's leaderboard.

    get_beatmap_scores

  4. Calculate shifts

    The AI processes the attributes and scores to show how mods affect the rating.

    get_beatmap_attributesget_beatmap_scores

Try it

Copy these to start.

Use these prompts to kick off your analysis.

Starting points

Swap out the map IDs and player names with the ones you actually want to check.

Osu! Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_idbAvUACFPzs9KS850RTtZmf4Xh5bSzXK57yhZpw/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — Osu! capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "osu-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_idbAvUACFPzs9KS850RTtZmf4Xh5bSzXK57yhZpw/mcp"
    }
  }
}
Copy into chat04

  • Analyze the difficulty of beatmap 123456 and tell me the star rating.

  • Compare the scores for player 'User123' and 'User456' on map 789101.

  • What are the attributes for beatmap 555666?

  • Calculate the star rating for map 112233 if I were to use the Hard Rock mod.

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect Osu! once, then ask.

One connection gives your agent access to the osu! API. Your credentials stay encrypted and secure.

Connect Osu! to your AI

FAQ

How the analysis behaves

  • 01

    Can the AI change my osu! profile settings?

    No. The AI can only read map and score data; it cannot modify your account or game settings.

  • 02

    Can it upload new beatmaps to the game?

    No. The tools only allow the AI to look up existing maps and their data.

  • 03

    How does it calculate mod-adjusted difficulty?

    It reads the base map attributes and applies the mathematical logic for specific mods to estimate the new rating.

  • 04

    Does it work with any map ID?

    Yes, as long as the map exists in the osu! database and can be found via the lookup tool.

  • 05

    Can I use this to find my friends' scores?

    Yes, you can ask the AI to pull scores for specific players on a given map.

  • More questions about Osu!? The Connector page answers them. See everything the Osu! Connector can do

Connect Osu! to Claude, Cursor, ChatGPT & more