osu! MCP

Name: osu! MCP
Author: Osyanne

本地服务

github.com/Osyanne游戏娱乐023 周前更新

代码仓库

关于 osu! MCP

osu! MCP 是面向 osu! 玩家和分析者的 MCP 服务，可供 Claude Desktop 等 MCP 客户端调用。它将玩家与成绩数据、谱面检索、排行榜及新闻整理为工具。

主要功能

01玩家资料与统计数据
02比较 2–5 名玩家
03浏览成绩与谱面
04全球及国家排行榜
05查看新闻与季节背景

适用场景

01查看玩家统计和成绩
02比较玩家表现
03按 BPM 或难度查找谱面
04查询各国顶尖玩家

MCP 相关

向 Claude Desktop 等 MCP 客户端提供 osu! API v2 数据与操作工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "osyanne-osu": {
      "command": "uvx",
      "args": [
        "osu-mcp"
      ],
      "env": {
        "OSU_CLIENT_ID": "<OSU_CLIENT_ID>",
        "OSU_CLIENT_SECRET": "<OSU_CLIENT_SECRET>"
      }
    }
  }
}

启动命令uvx osu-mcp

需要配置的环境变量

OSU_CLIENT_IDNumeric Client ID from your osu! OAuth application (https://osu.ppy.sh/home/account/edit).

OSU_CLIENT_SECRET密钥Client Secret from the same osu! OAuth application.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiosu-mcp0.1.4stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

osu-mcp

osu-mcp 是一个 Model Context Protocol（MCP）服务，可将 osu! API v2 作为工具提供给 Claude Desktop 和其他 MCP 客户端。用自然语言向 Claude 询问你的 osu! 个人资料、比较玩家、搜索谱面、浏览排名。

快速开始

1. 安装

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

2. 获取 osu! API 凭据

前往 https://osu.ppy.sh/home/account/edit
滚动到 OAuth，点击 New OAuth Application
名称：任意（例如“Claude Desktop”）；回调 URL：留空。
复制 Client ID 和 Client Secret。

3. 配置凭据

选项 A — 环境变量（推荐）：

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

选项 B — 配置文件，路径为 ~/.config/osu-mcp/config.toml（Linux/Mac）或 %APPDATA%\osu-mcp\config.toml（Windows）：

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

4. 接入 Claude Desktop

添加到 claude_desktop_config.json：

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

重启 Claude Desktop。你应该能在 MCP 服务列表中看到“osu”。

可用工具（12 个）

工具	描述
`get_user_summary`	个人资料和统计数据；可选择嵌入近期、最佳或首次成绩
`compare_users`	并排比较 2-5 位用户
`get_user_scores`	列出用户的最佳、近期或首次成绩
`get_score_details`	特定成绩的完整属性
`search_beatmaps`	使用筛选条件（模式、状态、难度、时长、BPM）搜索谱面集
`get_beatmap_details`	谱面的完整属性（AR/OD/CS/HP、BPM、最大连击数）
`get_beatmap_scores`	谱面上的最高分，可按 mods 筛选
`get_beatmapset`	包含所有难度的完整谱面集
`get_rankings`	pp/分数/图表排名，可查看全球或按国家筛选
`get_country_top`	指定国家 pp 排名中的前 N 名玩家
`get_news_posts`	osu! 最新新闻文章
`get_seasonal_backgrounds`	当前启用的季节性背景

完整参考：docs/tools.md。

示例

在 Claude Desktop 中试试：

“给我看看 peppy 的 osu! 数据”

“比较 Cookiezi 和 WhiteCat 的准确率和 pp”

“厄瓜多尔排名前 10 的 osu! 玩家有哪些？”

“帮我找一些 200 BPM 的流式 ranked 谱面”

开发

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/