{
  "markdown": "<!-- mcp-name: io.github.Osyanne/osu-mcp -->\n\n# osu-mcp\n\n[![PyPI](https://img.shields.io/pypi/v/osu-mcp.svg)](https://pypi.org/project/osu-mcp/)\n[![Tests](https://github.com/Osyanne/osu-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Osyanne/osu-mcp/actions/workflows/test.yml)\n[![Coverage](https://codecov.io/gh/Osyanne/osu-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/Osyanne/osu-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n> **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.\n\n## Quickstart\n\n### 1. Install\n\n```bash\nuv tool install osu-mcp\n# or\npip install osu-mcp\n```\n\n### 2. Get osu! API credentials\n\n1. Go to <https://osu.ppy.sh/home/account/edit>\n2. Scroll to **OAuth**, click **New OAuth Application**\n3. Name: anything (e.g., \"Claude Desktop\"); Callback URL: leave blank.\n4. Copy the **Client ID** and **Client Secret**.\n\n### 3. Configure credentials\n\n**Option A — environment variables (recommended):**\n```bash\nexport OSU_CLIENT_ID=12345\nexport OSU_CLIENT_SECRET=your-client-secret\n```\n\n**Option B — config file** at `~/.config/osu-mcp/config.toml` (Linux/Mac) or `%APPDATA%\\osu-mcp\\config.toml` (Windows):\n```toml\nclient_id = 12345\nclient_secret = \"your-client-secret\"\n```\n\n### 4. Wire up Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"osu\": {\n      \"command\": \"uvx\",\n      \"args\": [\"osu-mcp\"],\n      \"env\": {\n        \"OSU_CLIENT_ID\": \"12345\",\n        \"OSU_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. You should see \"osu\" in the MCP servers list.\n\n## Available tools (12)\n\n| Tool | Description |\n|---|---|\n| `get_user_summary` | Profile + stats; optionally embed recent/best/firsts scores |\n| `compare_users` | Side-by-side comparison of 2-5 users |\n| `get_user_scores` | List a user's best/recent/firsts scores |\n| `get_score_details` | Full attributes of a specific score |\n| `search_beatmaps` | Search beatmapsets with filters (mode, status, difficulty, length, BPM) |\n| `get_beatmap_details` | Full attributes of a beatmap (AR/OD/CS/HP, BPM, max combo) |\n| `get_beatmap_scores` | Top scores on a beatmap, filterable by mods |\n| `get_beatmapset` | Full beatmapset with all difficulties |\n| `get_rankings` | pp/score/charts rankings, global or by country |\n| `get_country_top` | Top N players of a country in pp ranking |\n| `get_news_posts` | Recent osu! news posts |\n| `get_seasonal_backgrounds` | Active seasonal backgrounds |\n\nFull reference: [docs/tools.md](docs/tools.md).\n\n## Examples\n\nIn Claude Desktop, try:\n\n> \"Show me peppy's osu! stats\"\n\n> \"Compare Cookiezi and WhiteCat on accuracy and pp\"\n\n> \"What are the top 10 osu! players from Ecuador?\"\n\n> \"Find me some 200 BPM streamy ranked maps\"\n\n## Development\n\n```bash\ngit clone https://github.com/Osyanne/osu-mcp.git\ncd osu-mcp\nuv sync\nuv run pytest                      # unit + smoke\nuv run pytest -m integration       # integration (needs real creds)\nuv run ruff check .\nuv run mypy --strict src/\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 3261,
  "sha": "a10df9d2966401a77b038b3a8ed735394bd7501cae68325331d56507c6da7de6",
  "repo_slug": "osyanne/osu-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_osyanne_osu_mcp_4b9b7112/readme"
}