English Français العربية

osu! MCP

Registre officiel Recherche et web

MCP server exposing the osu! API v2: player stats, scores, beatmap search, rankings.

Code source Documentation

Installation

Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).

PYPI package osu-mcp
Claude Code 
claude mcp add osu-mcp -e 'OSU_CLIENT_ID=<OSU_CLIENT_ID>' -e 'OSU_CLIENT_SECRET=<your osu_client_secret>' -- uvx osu-mcp==0.1.4
Configuration JSON (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "osu-mcp": {
            "command": "uvx",
            "args": [
                "osu-mcp==0.1.4"
            ],
            "env": {
                "OSU_CLIENT_ID": "<OSU_CLIENT_ID>",
                "OSU_CLIENT_SECRET": "<your osu_client_secret>"
            }
        }
    }
}

Variables d'environnement

  • OSU_CLIENT_ID obligatoire Numeric Client ID from your osu! OAuth application (https://osu.ppy.sh/home/account/edit).
  • OSU_CLIENT_SECRET obligatoire secret Client Secret from the same osu! OAuth application.

Documentation

Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.

Sommaire
  1. osu-mcp
  2. Quickstart
  3. Available tools (12)
  4. Examples
  5. Development
  6. License

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
  1. Go to https://osu.ppy.sh/home/account/edit
  2. Scroll to OAuth, click New OAuth Application
  3. Name: anything (e.g., "Claude Desktop"); Callback URL: leave blank.
  4. Copy the Client ID and Client Secret.
3. Configure credentials

Option A — environment variables (recommended):

export OSU_CLIENT_ID=12345
export OSU_CLIENT_SECRET=your-client-secret

Option B — config file at ~/.config/osu-mcp/config.toml (Linux/Mac) or %APPDATA%\osu-mcp\config.toml (Windows):

client_id = 12345
client_secret = "your-client-secret"
4. Wire up Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "osu": {
      "command": "uvx",
      "args": ["osu-mcp"],
      "env": {
        "OSU_CLIENT_ID": "12345",
        "OSU_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop. You should see "osu" in the MCP servers list.

Available tools (12)

ToolDescription
get_user_summaryProfile + stats; optionally embed recent/best/firsts scores
compare_usersSide-by-side comparison of 2-5 users
get_user_scoresList a user's best/recent/firsts scores
get_score_detailsFull attributes of a specific score
search_beatmapsSearch beatmapsets with filters (mode, status, difficulty, length, BPM)
get_beatmap_detailsFull attributes of a beatmap (AR/OD/CS/HP, BPM, max combo)
get_beatmap_scoresTop scores on a beatmap, filterable by mods
get_beatmapsetFull beatmapset with all difficulties
get_rankingspp/score/charts rankings, global or by country
get_country_topTop N players of a country in pp ranking
get_news_postsRecent osu! news posts
get_seasonal_backgroundsActive seasonal backgrounds

Full reference: docs/tools.md.

Examples

In Claude Desktop, try:

"Show me peppy's osu! stats"

"Compare Cookiezi and WhiteCat on accuracy and pp"

"What are the top 10 osu! players from Ecuador?"

"Find me some 200 BPM streamy ranked maps"

Development

git clone https://github.com/Osyanne/osu-mcp.git
cd osu-mcp
uv sync
uv run pytest                      # unit + smoke
uv run pytest -m integration       # integration (needs real creds)
uv run ruff check .
uv run mypy --strict src/

License

MIT — see LICENSE.

Questions fréquentes

Qu'est-ce que osu! MCP ?

MCP server exposing the osu! API v2: player stats, scores, beatmap search, rankings.

Comment installer osu! MCP ?

Il s'exécute sur votre machine. Dans Claude Code : claude mcp add osu-mcp -e 'OSU_CLIENT_ID=<OSU_CLIENT_ID>' -e 'OSU_CLIENT_SECRET=<your osu_client_secret>' -- uvx osu-mcp==0.1.4. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.

Faut-il une clé API pour osu! MCP ?

Oui. Il attend OSU_CLIENT_ID, OSU_CLIENT_SECRET, à renseigner dans sa configuration.

osu! MCP est-il open source ?

Oui. Son code est sur GitHub sous licence MIT.

Qui maintient osu! MCP ?

Il est publié par Osyanne. AI.tn le référence sans le maintenir ni le recommander.

Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.