maimai-mcp

本地可用的舞萌 DX 查询库 / CLI / MCP 服务：查曲、查分、进度与绘图，供命令行或任意 Agent / 宿主调用。

• 仓库：https://github.com/antinomie1/maimai-mcp
• 绘图与业务参考：Yuri-YuzuChaN/maimaiDX

Python ≥ 3.10。成绩默认走水鱼查分器，也可切换到落雪（需 Token / OAuth 绑定）。出图默认主题为 circle，可按 QQ 改为 prism_plus。

CLI 命令（maimai …）与 MCP 工具（maimai_*）能力一一对应；Agent 侧参数须包在 params 中，查分时每次显式传入玩家 qq 或 username（MCP 不会自动读聊天上下文）。

安装与配置

需要 Python ≥ 3.10。出图依赖外部 static 资源（不随包分发）。

1. 安装

任选其一：

安装后可用：

• maimai — 命令行
• maimai-mcp — stdio MCP 服务

也可用 python -m maimai_mcp.cli / python -m maimai_mcp。

2. 静态资源

1. 下载并解压资源包：
   • Cloudreve
   • OneDrive
2. 记下其中 static 目录的绝对路径（即 STATIC_PATH）。
3. 请遵守上游美术与字体相关声明。

3. 环境变量

写在 MCP 客户端的 env、系统环境，或 maimai_mcp/.env。完整列表见 .env.example。

4. 接入 MCP

推荐配置（uvx，不必事先 install）：

{
  "mcpServers": {
    "maimai": {
      "command": "uvx",
      "args": ["maimai-mcp"],
      "env": {
        "STATIC_PATH": "/path/to/static",
        "OUTPUT_DIR": "/path/to/output",
        "DIVINGFISH_TOKEN": ""
      }
    }
  }
}

说明：

• 路径改成你的机器上的真实路径；Windows 示例："C:\\path\\to\\static"
• 若已 uv tool install 或 pip install，可改为 "command": "maimai-mcp"，并去掉 args
• 更多字段见 mcp.example.json
• Agent 调用约定见 skills/maimai-mcp/

5. 自检

maimai update tables
maimai b50 --qq <QQ>
maimai chart 834

能出图、客户端能列出 maimai_* 工具即可。

从源码开发

仅二次开发或跟踪仓库最新代码时需要：

git clone https://github.com/antinomie1/maimai-mcp.git
cd maimai-mcp
uv sync                 # 或 pip install -e .
# 开发依赖：uv sync --extra dev
cp maimai_mcp/.env.example maimai_mcp/.env   # 至少填 STATIC_PATH

静态资源与环境变量见上文。MCP 可在仓库目录用 uv run：

{
  "mcpServers": {
    "maimai": {
      "command": "uv",
      "args": ["run", "maimai-mcp"],
      "cwd": "/path/to/maimai-mcp",
      "env": {
        "STATIC_PATH": "/path/to/static",
        "DIVINGFISH_TOKEN": ""
      }
    }
  }
}

自检：uv run maimai update tables、uv run maimai b50 --qq <QQ>。
联调：scripts/run_inspector.ps1、scripts/smoke_mcp_tools.py。

工具列表

以下为 MCP 工具名与简要说明。CLI 侧为同名能力（例如 maimai b50 对应 maimai_b50）。
查分 / 出图类工具通常需要 params.qq 或 params.username；出图默认 format: image，成功时返回 image_path。

更细的 Agent 约定见 skills/maimai-mcp/references/tools.md。

成绩与进度

曲库与谱面

组合工作流

只需要上分列表时，优先直接调用 maimai_rise。

用户设定（按 QQ 本地存储）

设定保存在本地 user.db。查分时会自动使用该 QQ 已保存的主题与数据源；默认水鱼。仅在用户明确要求切换时再改设定。

官服成绩上传

将机台扫码成绩导入 水鱼 / 落雪时：

1. 在水鱼网页「编辑个人资料」生成 Import-Token（不是 开发者 DIVINGFISH_TOKEN）。
2. 绑定到本地 user.db：

maimai user bind-import --qq <QQ> --token <Import-Token>
maimai user show --qq <QQ>   # 可见 import_token 绑定状态（掩码）

3. 确保曲库缓存为水鱼 /music_data（static/data/music_data.json）：

maimai update music

4. 一键：扫码内容 → dump → convert → 上传。必须声明数据源 --source：

# 水鱼（需 bind-import）
maimai records update --qq <QQ> --qr-content 'SGWC...' --source divingfish

# 落雪（需先 maimai user bind 落雪 OAuth，scope 含 write_player）
maimai records update --qq <QQ> --qr-content 'SGWC...' --source lxns

# 水鱼 + 落雪
maimai records update --qq <QQ> --qr-content 'SGWC...' --source both

MCP：maimai_update_records 的 params.source 必填：divingfish | lxns | both（也可用 target 别名）。
响应含 source / sources / source_label。

可选：身份缓存与群榜

两套本地数据，职责分离：

只有查群榜时才会去拉成员成绩（默认并发 3、启动间隔 250ms）；新鲜缓存（默认 24h，PLAYER_CACHE_TTL_SECONDS）会复用，避免重复打满 API。后台不会预拉全群。

身份

常规查分请直接传 params.qq，不必依赖昵称反查。

群内榜

与 maimai_ranking（水鱼公开总榜）不同：群榜只比本群成员。

推荐：先有身份名册 → 用户要榜时直接调群榜工具。限速可用 GROUP_RANK_MAX_CONCURRENCY / GROUP_RANK_QUERY_DELAY_MS。Agent 约定见 skills/maimai-mcp/。

License

• 本仓库代码：BSD-2-Clause
• 参考自 maimaiDX 的部分：MIT（见 LICENSE-UPSTREAM）
• static 等美术 / 字体资源不随包分发，版权以资源包与官方声明为准，不在本许可范围内

致谢

• Yuri-YuzuChaN/maimaiDX — 绘图与业务参考
• Diving-Fish 查分器
• 落雪查分器
• 柚子别名