Skip to main content
Glama
antinomie1

maimai-mcp

by antinomie1
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

maimai-mcp

PyPI Python MCP Badge

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

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

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

安装与配置

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

1. 安装

任选其一：

方式

命令

uv 工具（推荐）

uv tool install maimai-mcp

uv 临时运行

uvx maimai-mcp（只跑 MCP，不装全局命令）

pip

pip install maimai-mcp

安装后可用：

  • maimai — 命令行

  • maimai-mcp — stdio MCP 服务

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

2. 静态资源

  1. 下载并解压资源包：

  2. 记下其中 static 目录的绝对路径（即 STATIC_PATH）。

  3. 请遵守上游美术与字体相关声明。

3. 环境变量

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

变量

必填

说明

STATIC_PATH

是

上一步 static 的绝对路径

DIVINGFISH_TOKEN

建议

水鱼开发者 Token，不是 Import-Token

OUTPUT_DIR

否

出图目录

NAPCAT_BASE_URL

否

身份缓存 / 群名册（OneBot HTTP）

QQ_IDENTITY_CACHE_DIR

否

身份缓存目录，默认 ./qq-identity-cache

PLAYER_CACHE_DIR

否

群榜用成绩缓存目录，默认 ./player-cache

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_* 工具即可。

Related MCP server: Claud-Ear

从源码开发

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

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_b50

拉取并绘制 Best 50；水鱼可用 username，绑定服务可用 qq。all_perfect=true 为 AP50（需落雪 + 已绑定 QQ）

maimai_minfo

单曲个人成绩（minfo），须指定玩家身份

maimai_score_list

按等级或定数（如 14.0）列出该玩家已打 / 相关分数

maimai_plate

牌子完成表或进度图（如 ver=祝 plan=将，mode=progress / table）

maimai_plate_status

与 maimai_plate 等价的薄封装，便于 Agent 发现「牌子进度」意图

maimai_rating_table

等级定数表；progress=true 时叠加个人完成情况

maimai_level_progress

某等级 + 目标的完成进度（如 level=14 plan=ap）

maimai_rise

上分推荐谱面，可按等级 / 分数等条件筛选

maimai_ranking

水鱼公开 rating 榜；可查榜、搜名，或 my=true 看自己位置

maimai_fortune

今日运势 + 曲绘（娱乐向；qq / username 仅作随机种子）

曲库与谱面

工具

说明

maimai_search

按曲名、定数、BPM、曲师、谱师等搜索；多结果返回列表，唯一命中时可直接出谱面图

maimai_lookup_song

组合：搜索 → 出谱面图；可选 with_minfo 附带个人成绩（内部串联 search + chart ± minfo）

maimai_chart

按 ID / 曲名 / 别名绘制谱面信息图；可选带玩家身份以计算推分

maimai_score_line

计算指定达成线（如 100%）下的 TAP GREAT 容错

maimai_random

按等级 / 谱面类型 / 颜色随机一首并出谱面图

maimai_mai_what

随机推曲；rise=true 时偏向有上分空间的谱面

maimai_alias_query

查询某曲的别名列表

maimai_alias_local_add

仅写入本地的别名（不上报远端投票）

maimai_update_catalog

刷新曲库数据、别名，和/或重绘定数表、牌子表资源

组合工作流

工具

说明

maimai_player_overview

玩家概览：B50 图/数据，并可附带上分推荐 JSON（不必当作每条消息的默认动作）

maimai_push_plan

上分计划：推荐增益谱面，并为第一条推荐曲出谱面图

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

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

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

工具

说明

maimai_user_show

查看主题、默认查分源、Import-Token 绑定状态（须传 qq）

maimai_user_set_theme

设置出图主题：circle（默认）或 prism_plus

maimai_user_set_source

设置默认查分源：水鱼或落雪

maimai_user_bind_lxns

获取落雪 OAuth 授权链接，或提交 code 完成绑定

官服成绩上传

工具

说明

maimai_user_bind_import_token

绑定水鱼 Import-Token（个人资料页生成，不是 DIVINGFISH_TOKEN）

maimai_update_records

机台扫码 → dump → convert → 上传；params.source 必填 divingfish | lxns | both

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

  1. 在水鱼网页「编辑个人资料」生成 Import-Token（不是 开发者 DIVINGFISH_TOKEN）。

  2. 绑定到本地 user.db：

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

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

maimai update music

  1. 一键：扫码内容 → 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。

可选：身份缓存与群榜

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

缓存

环境变量

内容

写入时机

身份

QQ_IDENTITY_CACHE_DIR（默认 ./qq-identity-cache）

群成员、群名片、好友昵称

maimai_refresh_identity（需 NAPCAT_BASE_URL）

成绩

PLAYER_CACHE_DIR（默认 ./player-cache）

Rating / 单曲快照

查群榜时按需拉取；个人 b50/minfo 也会旁路写入

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

身份

工具

说明

maimai_refresh_identity

经 OneBot / NapCat 刷新好友与群成员（不查成绩）

maimai_identity_status

身份缓存状态

maimai_resolve_qq

昵称 / 群名片 → QQ

maimai_get_qq_identity

按 QQ 读缓存昵称等信息

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

群内榜

工具

说明

maimai_group_rating_rank

本群 Rating 榜（查榜时按需拉分）

maimai_group_song_rank

本群某曲成绩榜（查榜时按需拉该曲）

maimai_group_member_rank

某人在群内 Rating 或某曲的名次

maimai_player_cache_status

成绩缓存覆盖统计

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

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

License

  • 本仓库代码：BSD-2-Clause

  • 参考自 maimaiDX 的部分：MIT（见 LICENSE-UPSTREAM）

  • static 等美术 / 字体资源不随包分发，版权以资源包与官方声明为准，不在本许可范围内

致谢

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
7Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • mcp-aichat

    MCP server for AI dialogue using various LLM models via AceDataCloud

  • mcp-producer

    MCP server for Producer/Riffusion AI music generation

  • mcp-glm

    MCP server for GLM chat completions using Zhipu AI models via AceDataCloud

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/antinomie1/maimai-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server