osu! MCP

io.github.OsyannePublished by GitHub account Osyannev0.1.4Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

A local MCP server that exposes the osu! API v2, letting an assistant look up player stats, scores, beatmaps, rankings and news in natural language.

What you can do
Look up player profiles and stats, and compare two to five players side by side on accuracy, pp and similar metrics. List a player's best, recent or first-place scores and fetch full details of a specific score. Search beatmapsets by mode, status, difficulty, length and BPM, and get full beatmap or beatmapset details including AR/OD/CS/HP, BPM and max combo. View top scores on a beatmap, filterable by mods. Browse pp, score and charts rankings globally or by country, and list a country's top players. Read recent osu! news posts and active seasonal backgrounds.
When to use it
Useful when you want to ask about osu! players, compare their performance, find beatmaps matching criteria such as BPM or difficulty, or check rankings and news without leaving the chat client.
Requirements
Runs locally as a Python package (osu-mcp) installed with uv or pip, on desktop MCP clients such as Claude Desktop. Needs an osu! OAuth application's Client ID and Client Secret, supplied through the OSU_CLIENT_ID and OSU_CLIENT_SECRET environment variables or a local config file. Requires network access to the osu! API.
Before you install
Requires an osu! OAuth Client Secret (OSU_CLIENT_SECRET); the README suggests putting it in environment variables or a plain config file, so keep it out of shared configs and version control. Access is read-only lookups of public osu! data; no writes, payments or wallet keys are involved.

Installation

In SourceWeft

  1. Open osu! MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

osu-mcp

[PyPI] [Tests] [Coverage] [License: MIT]

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

bash
export OSU_CLIENT_ID=12345export 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 = 12345client_secret = "your-client-secret"

4. Wire up Claude Desktop

Add to claude_desktop_config.json:

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

bash
git clone https://github.com/Osyanne/osu-mcp.gitcd osu-mcpuv syncuv run pytest                      # unit + smokeuv run pytest -m integration       # integration (needs real creds)uv run ruff check .uv run mypy --strict src/

License

MIT — see LICENSE.

Source: README.md at commit 5ffcf1b

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts