Metadata-Version: 2.4
Name: osu-mcp
Version: 0.1.1
Summary: MCP server exposing osu! API v2 as tools for Claude and other MCP clients
Project-URL: Homepage, https://github.com/Osyanne/osu-mcp
Project-URL: Repository, https://github.com/Osyanne/osu-mcp
Project-URL: Issues, https://github.com/Osyanne/osu-mcp/issues
Project-URL: Changelog, https://github.com/Osyanne/osu-mcp/blob/main/CHANGELOG.md
Author-email: Imanol Miranda <imanolmiranda102004@gmail.com>
License: MIT
License-File: LICENSE
Keywords: anthropic,api,claude,mcp,osu,rhythm-game
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: cachetools>=5.0
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: ossapi>=4.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# osu-mcp

[![PyPI](https://img.shields.io/pypi/v/osu-mcp.svg)](https://pypi.org/project/osu-mcp/)
[![Tests](https://github.com/Osyanne/osu-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Osyanne/osu-mcp/actions/workflows/test.yml)
[![Coverage](https://codecov.io/gh/Osyanne/osu-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/Osyanne/osu-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **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.

> 🚧 v0.1 — demo GIF placeholder (recorded in v0.1.1).

## Quickstart

### 1. Install

```bash
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):**
```bash
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`:

```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](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](LICENSE).
