How do I install the osu! MCP MCP server?

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "osu-mcp": { "command": "npx", "args": ["-y", "osu! MCP"] } }

What does osu! MCP do?

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

Is the osu! MCP MCP server free to use?

Yes. osu! MCP is listed on AllMCPs as a free, open Model Context Protocol server you can install into Claude Desktop, Cursor, or any MCP-compatible client.

How do I install the osu! MCP MCP server?

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "osu-mcp": { "command": "npx", "args": ["-y", "osu! MCP"] } }

What does osu! MCP do?

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

Is the osu! MCP MCP server free to use?

Yes. osu! MCP is listed on AllMCPs as a free, open Model Context Protocol server you can install into Claude Desktop, Cursor, or any MCP-compatible client.

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

bash

uv tool install osu-mcp
# or
pip install osu-mcp

2. Get osu! API credentials

Go to https://osu.ppy.sh/home/account/edit
Scroll to OAuth, click New OAuth Application
Name: anything (e.g., "Claude Desktop"); Callback URL: leave blank.
Copy the Client ID and Client Secret.

3. Configure credentials

Option A — environment variables (recommended):

server.ts

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):

toml

client_id = 12345
client_secret = "your-client-secret"

4. Wire up Claude Desktop

Add to claude_desktop_config.json:

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)

Tool	Description
`get_user_summary`	Profile + stats; optionally embed recent/best/firsts scores
`compare_users`	Side-by-side comparison of 2-5 users
`get_user_scores`	List a user's best/recent/firsts scores
`get_score_details`	Full attributes of a specific score
`search_beatmaps`	Search beatmapsets with filters (mode, status, difficulty, length, BPM)
`get_beatmap_details`	Full attributes of a beatmap (AR/OD/CS/HP, BPM, max combo)
`get_beatmap_scores`	Top scores on a beatmap, filterable by mods
`get_beatmapset`	Full beatmapset with all difficulties
`get_rankings`	pp/score/charts rankings, global or by country
`get_country_top`	Top N players of a country in pp ranking
`get_news_posts`	Recent osu! news posts
`get_seasonal_backgrounds`	Active 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

bash

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.

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

bash

uv tool install osu-mcp
# or
pip install osu-mcp

2. Get osu! API credentials

Go to https://osu.ppy.sh/home/account/edit
Scroll to OAuth, click New OAuth Application
Name: anything (e.g., "Claude Desktop"); Callback URL: leave blank.
Copy the Client ID and Client Secret.

3. Configure credentials

Option A — environment variables (recommended):

server.ts

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):

toml

client_id = 12345
client_secret = "your-client-secret"

4. Wire up Claude Desktop

Add to claude_desktop_config.json:

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)

Tool	Description
`get_user_summary`	Profile + stats; optionally embed recent/best/firsts scores
`compare_users`	Side-by-side comparison of 2-5 users
`get_user_scores`	List a user's best/recent/firsts scores
`get_score_details`	Full attributes of a specific score
`search_beatmaps`	Search beatmapsets with filters (mode, status, difficulty, length, BPM)
`get_beatmap_details`	Full attributes of a beatmap (AR/OD/CS/HP, BPM, max combo)
`get_beatmap_scores`	Top scores on a beatmap, filterable by mods
`get_beatmapset`	Full beatmapset with all difficulties
`get_rankings`	pp/score/charts rankings, global or by country
`get_country_top`	Top N players of a country in pp ranking
`get_news_posts`	Recent osu! news posts
`get_seasonal_backgrounds`	Active 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

bash

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.

Osu! MCP

Quick Install

Install Config Generator

Documentation Overview

osu-mcp

Quickstart

1. Install

2. Get osu! API credentials

3. Configure credentials

4. Wire up Claude Desktop

Available tools (12)

Examples

Development

License

Related MCP Servers

Frequently Asked Questions about Osu! MCP

AllMCPs Directory Badge

Technical Specs & Signals

Feature Your MCP Server

Own this project?

Share & Embed

Explore more

Osu! MCP

Quick Install

Install Config Generator

Documentation Overview

osu-mcp

Quickstart

1. Install

2. Get osu! API credentials

3. Configure credentials

4. Wire up Claude Desktop

Available tools (12)

Examples

Development

License

Related MCP Servers

Frequently Asked Questions about Osu! MCP

AllMCPs Directory Badge

Technical Specs & Signals

Feature Your MCP Server

Own this project?

Share & Embed

Explore more