maimai-mcp

maimai-mcp [](https://pypi.org/project/maimai-mcp/0.2/) [](https://pypi.org/project/maimai-mcp/) [](https://lobehub.com/mcp/antinomie1-maimai-mcp) Locally available maimai DX query library / CLI / MCP service: query songs, scores, progress and generate charts, for command line or any Agent / host to- Repository: https://github.com/antinomie1/cp - Chart and business reference: [Yuri-YuzuChaN/maimaiDX](https://github.com/Yuri-YuzuChaN/maimaiDX) Python ≥ 3.10. Score queries default to [Diving-Fish](https://www.diving-fish.com/maimaidx/prober/), but can be switched to [Luo Xue](https://maimai.lxns.net/) (requires Token / OAuth binding). chart theme is **circle**, which can be changed to **_plus** via QQ. CLI commands (`maimai …`) tools (`maimai_*`) have one-to-one correspondence; parameters must be wrapped in `params`, and when querying `qq` or `username` must be explicitly passed (M not automatically read chat context). ## Installation and Configuration Requires **Python ≥ 3.10**. Chart generation depends onstatic** resources (not distributed with the package). ### 1. Installation Choose one: | Method | Command | |------|------| | uv tool (recommended) | `uv tool install maimai-mcp` | | uv temporary run | `uvx maimai-mcp` (only runs MCP, does not install global command) | | pip | `pip install maimai-mcp` | After installation, available: - `maimai` — Command line - `maimai-mcp` — stdio MCP service Also available: `python -m maimai_mcp.cli` / `python -m maimai_mcp`. ### 2. Static Resources 1. Download and extract resource package: - [Cloudhttps://cloud.yan.moe/fs7/20CN1.55. - [OneDrive](https://yuzuaipoint.com/:g/personal/yuzu_yuzuchan_moe/IKHie6MAa3rME7Q-ruAVKgXDCKROqz5e25KtMeeVY?e=53eC6a) 2. Note the absolute path of the **`static` directory** (i.e., `STATIC_PATH`). Please comply with upstream art and font related statements. ### 3. Environment Variables Write in MCP client's `env`, system environment, or `maimai_mcp/.env`. Complete list see [`.env.example`](maimai_mcp/.env.example). Required | Description | |------|------|------| | `` | **Yes Absolute path of `static` directory | | `DIVINGFISH_TOKEN` | Recommended | [Diving-Fish developer Token](https://www.diving-fish.com/maimaidx/prober/), **not** Import-Token | | `OUTPUT_DIR` | No | Chart output directory | | `NAPCAT_BASE_URL` | No | Identity cache / group roster (OneBot HTTP) | | `QQ_IDENTITY_CACHE_DIR` | No | Identity cache directory, default `./qq-identity-cache` | | `PLAYER_CACHE_DIR` | No | Group ranking score cache directory, default `./player-cache` | ### 4. MCP Integration Recommended configuration (`uvx`, no need to install beforehand): ```json { "mcpServers": { "maimai": { "command": "uvx", "args": ["maimai-mcp"], "env": { "STATIC_PATH": "/path/to/static", "OUTPUT_DIR": "/path/to/output", "DIVINGFISH_TOKEN": "" } } } } ``` Description: - Change paths to real paths on your machine; Windows example: `"C:\\path\\to\\static"` - If already `uv tool install` or `pip install`, can change to `"command": "maimai-mcp"` and remove `args` - More fields see [`mcp.example.json`](mcp.example.json) - Agent call conventions see [`skills/maimai-mcp/`](skills/maimai-mcp/) ### 5. Self-test ```bash maimai update tables maimai b50 --qq <QQ> maimai chart 834 ``` Able to generate charts, and client can list `maimai_*` tools. ## Development from Source Only needed for secondary development or tracking repository updates: ```bash git clone https://github.com/antinomie1/maimai-mcp.git cd maimai-mcp uv sync # or pip install -e . # Development dependencies: uvextra dev cp maimai_mcp/.env.example maimai_mcp/.env # At least fill STATIC_PATH ``` Static resources and environment variables see above. MCP can be run in the repository directory using `uv run`: ```json { "mcpServers": { "maimai": { "command": "uv", "args": ["run", "maimai-mcp"], "cwd": "/path/to/maimai-mcp", "env": { "STATIC_PATH": "/path/to/static", "DIVINGFISH_TOKEN": "" } } } } ``` Self-test: `uv run maimai update tables`, `uv run maimai b50 --qq <QQ>`. Debugging: `scripts/run_inspector.ps1`, `scripts/smoke_mcp_tools.py`. ## Tool List The following are MCP tool names and brief descriptions. CLI side has the same capabilities (e.g., `maimai b50` corresponds to `maimai_b50`). Score/query tools usually require `params.qq` or `params.username`; chart generation defaults to `format: image`, returns `image_path` on success. See more detailed Agent conventions in [`skills/maimai-mcp/references/tools.md`](skills/maimai-mcp/references/tools.md). ### Scores and Progress | Tool | Description | |------|------| | `maimai_b50` | Pull and draw Best 50; Diving-Fish can use `username`, bound service can use `qq`. `all_perfect=true` for AP50 (requires Luo Xue + QQ bound) | | `maimai_minfo` | Single song personal score (minfo), must specify player identity | | `maimai_score_list` | List scores by level or constant (e.g.,.0`); show played/related scores | | `maimai_plate` | Plate completion table or progress chart (e.g., `ver=祝` `plan=将`, `mode=progress` / `table`) | | `maimai_plate_status` | Thin wrapper of `maimai_plate` for Agent to discover "plate progress" intent | | `maimai_rating_table` | Level constant table; add personal completion when `progress=true` | | `maimai_level_progress` | Completion progress of a level + target (e.g., `level=14` `plan=ap`) | | `maimai_rise` | Score recommendation, filterable by level / score | | `maimai_ranking` | Diving-Fish public rating ranking; query ranking, search by name, or `my=true` to see own position | | `maimai_fortune` | Today's luck + song illustration (entertainment; `qq` / `username` only for random seed) | ### Song Library and Charts | Tool | Description | |------|| `maimai | Search by song name, constant, BPM, artist, or designer; multiple results return list, unique hit returns | | `maimai_lookup_song` | Combination: search → draw chart; optional `with_minfo` with personal score (internally linked search + chart ± minfo) | | `maimai_chart Draw chart information by ID / song name / alias; player identity to calculate| `maimai` | Calculate TAP GREAT specified achievement line (e.g., 100%) `maimai_random` | Randomly select a song / chart type / draw chart | | `_mai_what` | Random song recommendation;=true` for songs improvement potential | |imai_alias_query` | Query alias list of a song `maimai_alias` | Only add local alias (no remote voting) | | `maimai_update | Refresh song library aliases, and/or table, plate table resources | ### Combined Workflow | | |------|| `maimaiview` | Player overview50 chart/data, score improvement JSON (not default action for every message| `maimai_push_plan Score improvement plan beneficial songs and draw first recommended song | When only score improvement list is needed, directly call `maimai_rise`. ### User Settings (stored locally by QQ) Settings are saved in local `user Score queries will automatically theme and data source saved for that QQ; **default to Diving-Fish**. Only change settings when explicitly requested. | Tool | Description | |------|------| | `maimai_user_show` | Show theme, default score query source, Import-Token binding status (must pass `qq`) | | `maimai_user_set_theme` | Set chart theme: `circle` (default) or `prism_plus` | maimai_user_set_source` | Set default score query source: Diving-Fish or Luo Xue | | `maimai_user_bind_lxns` | Get Luo Xue OAuth authorization link or submit `code` to | ### Official Server Score| Tool | Description | |------|------| | `maimai_user_bind_import | Bind Diving **Import-Token** (generated on personal profile page `DIVINGF`) | | `maimai_update_records` | code → dump → convert → upload; **`` required**: `fish` | `lx | `both` import scanned score toiving-Fish](https://www.diving-f/maimaidx/prober/) / Luo Xue: 1. Generate **Import** on Diving-Fish personal profile page (**not** developer `DIVINGFISH_TOKEN`). 2. Bind to local `user.dbbash maimai-import --qq <QQ> --token <Import-Token> maimai user show --qq <QQ> # See import_token binding status (masked) ``` 3. Ensure song library cache is Diving-Fish `/music_data` (`static/data/music_data.json`): ```bash maimai update music ``` 4. One-click: scan QR code content → dump → convert → upload. **Must declare data source `--source`**: ```bash # Diving-Fish (need bind-import) maimai records update --qq <QQ> --qr-content 'SGWC...' --source divingfish #need maimai user bind Luo Xue OAuth, scope contains write_player) maimai records update --qq <QQ> --qr-content 'SGWC...' --source lxns # Both Diving-Fish and Luo Xue maimai records update --qq <QQ> --qr-content 'SGWC...' --source both ``` MCP: **`params.source` required**: `divingfish` | `lxns` | `both` (also use `target` alias). Response contains `source` / `sources` / `source_label`. ### Optional: Identity Cache and Group Ranking Two sets of local data, separated by responsibility: | Cache | Environment Variable | Content | Write Timing | |------|----------|------|----------| | Identity | `QQ_IDENTITY_CACHE_DIR` (default `./qq-identity-cache`) | Group members, group nicknames, friend nicknames | `maimai_refresh_identity` (requires `NAPCAT_BASE_URL`) | | Score | `PLAYER_CACHE_DIR` (default `./player-cache`) | Rating / single song snapshot | **Queried when group ranking is checked**; personal50`/`minfo` also writes cache | group ranking queries will pull member scores** (default concurrency 3, interval 250ms); fresh cache (default 24h, `PLAYER_CACHE_TTL_SECONDS`) will be reused to avoid repeated API calls. Background will not pre-pull entire group. #### Identity | Tool | Description | |------|------| | `maimai_refresh_identity` | Refresh friend and group members via OneBot / NapCat (no score query) | | `maimai_identity_status` | Identity cache status | | `maimai_resolve_qq` | Nickname / group nickname → QQ | | `maimai_get_qq_identity` | Read cached nickname information by QQ | Regular score queries, please directly pass `params.qq`, no need to rely on nickname reverse query. #### Group Ranking | Tool | Description | |------|------| | `maimai_group_rating_rank` | ranking (query scores when checking ranking) | |imai_group_song_rank` | Group song score ranking (query scores when checking ranking) | | `maimai_group_member_rank` | Member's ranking in group rating | | `ma_cache_status` | coverage statistics | Differentmaimai_rankingDiving-Fish public ranking): group ranking onlythis group members**. have identity roster when user requests ranking, directly call group ranking tool. Rate limiting available: `GROUP_RANK_MAX_CONCURRENCY` / `GROUP_RANK_QUERY_DELAY_MS`. Agent conventions see [`skills/maimai-mcp/`](skills/maimai-mcp/). ## License - This repository code: **[BSD-Clause](LICENSE) Referenced from [maimaiDX](https:///Yuri-YuzuChaN/maimai **MIT** (LICENSE-UPSTREAM](LICENSE-UPSTREAM)) - `static` and other art / font resources **not distributed with package**, copyright and licensing as per resource package and official statements ## Acknowledgements - [Yuri-YuzuChaN/maimaiDX](https://github.com/Yuri-YuzuChaN/maimaiDX) — Chart and business reference - [Diving](https://www.diving-fish.com/maimaidx/prober/) - [Luo Xue](https://maimai.lxns.net/) - [Yuzu Alias](https://www.yuzuchan.moe/)