cubism-mcp 1.0.0

MCP server for Live2D Cubism Editor external API integration

Cubism External Edit MCP

中文 | English | 日本語 | 한국어

将 Live2D Cubism Editor 的外部应用集成 API 封装为 MCP (Model Context Protocol) 工具，让 AI Agent 通过自然语言操控 Cubism Editor 进行建模操作。

官方下载及参考文档：https://creatorsforum.live2d.com/t/topic/3938

架构

AI Agent
    │
    │ stdio (MCP Protocol)
    │
┌───▼──────────────────────┐
│  cubism_mcp.py    │  ← 本项目
│  (MCP Server, 17 Tools)  │
└───┬──────────────────────┘
    │
    │ WebSocket (ws://localhost:22033)
    │
┌───▼──────────────────────┐
│  Cubism Editor 5.4 Alpha │
│  (外部应用集成 API)        │
└──────────────────────────┘

功能特性

• 读写操作 — 读取/写入模型参数值、查看文档列表、获取编辑模式（适用 Editor 4.x+）
• 完整模型查询 — 参数结构、部件结构、变形器结构、单个对象详情（需 5.4 Alpha）
• 编辑操作 — 增删改查参数/部件/变形器/ArtMesh/Glue，自动事务包裹（需 5.4 Alpha）
• 批量编辑 — 同一事务内执行多个操作，任一失败自动回滚
• 权限分级 — 读写需 Allow 授权，编辑需 Edit 授权
• 自动重连 — Editor 重启后自动重连，3 秒间隔
• Token 持久化 — 认证令牌缓存到 ~/.cubism-mcp/token.txt，避免重复授权

环境要求

组件	版本
Python	≥ 3.10
Cubism Editor	5.4 Alpha（有效期至 2026-09-14）
操作系统	Windows / macOS

使用流程

快速开始

复制以下提示词发给你的 AI Agent：

根据 https://github.com/nana7chi/CubismExternalEditMCP/blob/master/README.md 完成 cubism-mcp 的安装和配置。如果电脑上还没有 uv，请先帮我安装。配置完成后告诉我是否就绪。

第一步：安装 uv（仅一次）

uv 是一个极小的 Python 包管理器，用于自动安装和运行本 MCP。安装后无需再管 Python 环境。

macOS（终端粘贴运行）：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell 粘贴运行）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后重启终端，输入 uv --version 能看到版本号即成功。

第二步：在 AI Agent 中配置 MCP

支持 ClaudeCode, Codex, Workbuddy 等各种支持MCP的客户端

第一次启动会自动下载依赖包，耗时约 1–2 分钟，之后秒启。

方式一：uvx 在线运行（推荐）

添加以下MCP配置：

{
  "mcpServers": {
    "cubism-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nana7chi/CubismExternalEditMCP.git", "cubism-mcp"],
      "description": "Cubism Editor MCP",
      "env": { "NO_PROXY": "localhost,127.0.0.1" }
    }
  }
}

方式二：本地克隆运行

1. 克隆源码到本地(或下载ZIP并解压)

git clone https://github.com/nana7chi/CubismExternalEditMCP.git

2. 添加以下MCP配置（修改 cwd 为实际路径）：

{
  "mcpServers": {
    "cubism-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["cubism_mcp.py"],
      "cwd": "J:/修改为实际路径/CubismExternalEditMCP",
      "description": "Cubism Editor MCP",
      "env": { "NO_PROXY": "localhost,127.0.0.1" }
    }
  }
}

第三步：在 Cubism Editor 中开启外部集成

1. 启动 Cubism Editor 5.4 Alpha，打开一个模型
2. 菜单「文件」→「外部应用程序集成的设置」
3. 确认端口为 22033，打开「使用」开关
4. 弹出授权对话框，找到 cubism-mcp，勾选 Allow 和 Edit，点 OK

如果没看到弹窗，检查 Editor 右下角是否有闪烁的外部应用图标，点击即可打开对话框。

第四步：开始使用

在 AI Agent 中用自然语言操控 Editor，例如：

"列出当前模型的参数结构"
"查看部件层级"
"把眉毛部件的标签色改成蓝色"
"新建参数 ParamsTest，ID 为 ParamTest，范围 0-1，默认 0.5"
"批量添加 3 个关键帧到 ParamAngleX"

注意：每次重启 Cubism Editor 后，都需要重新开启「外部应用集成」开关并勾选 Allow + Edit 权限。

可用工具

诊断

工具	说明
cubism_status	检查连接状态、注册状态、Allow/Edit 授权

读写操作

工具	参数	说明
cubism_get_model_uid	—	获取当前打开模型的 UID
cubism_get_documents	—	列出所有打开的文档（建模/物理/动画）
cubism_get_document	document_uid	按 UID 获取单个文档详情
cubism_get_current_edit_mode	—	获取编辑模式（Physics/Modeling/Animation/…）
cubism_get_parameter_values	model_uid, ids?	读取模型参数当前值
cubism_set_parameter_values	model_uid, parameters[]	写入参数值（无需编辑事务）
cubism_clear_parameter_values	model_uid	清除 SetParameterValues 的临时缓存
cubism_get_parameters	model_uid	参数元信息（名称/范围/Keyform/类型）
cubism_get_parameter_groups	model_uid	参数组列表

查询结构（5.4 Alpha 新增）

工具	参数	说明
cubism_get_parameter_structure	model_uid	参数完整结构树（组+参数层级）
cubism_get_part_structure	model_uid	部件结构树（ArtMesh/Deformer/Part/Glue）
cubism_get_deformer_structure	model_uid	变形器结构树
cubism_get_object	model_uid, id	获取指定对象详情
cubism_get_selected	model_uid	获取当前选中的对象列表

编辑操作（5.4 Alpha 新增）

工具	参数	说明
cubism_edit	action, params	执行单个编辑（自动 Begin/End 事务）
cubism_edit_batch	actions[]	批量编辑（同一事务，失败自动回滚）

支持的编辑 Action

Action	主要参数	说明	提示词示例
AddParameter	GroupId, ParameterName, ParameterId, Default, Minimum, Maximum	添加参数到指定组	"新建参数'测试'，ID为ParamTest，范围0~1，默认0.5，放在'表情切换'组"
EditParameter	Id, ParameterName, Default, Minimum, Maximum	编辑参数属性	"把ParamTest的最大值改成2"
DeleteParameter	Id	删除参数	"删除ParamTest参数"
AddParameterGroup	GroupName, GroupId, ParentGroupId	添加参数组	"新建参数组'测试组'"
EditParameterGroup	Id, GroupName, LabelColorType, LabelCustomColor	编辑参数组属性	"把'XYZ'组的标签色改成蓝色"
MoveParameter	Id, NewGroupId, InsertPosition	移动参数到新位置/组	"把ParamTest移到'XYZ'组最前面"
MoveParameterGroup	Id, InsertPosition	调整参数组顺序	"把'眉毛'组移到第一位"
AddParameterKey	ParameterId, KeyValue	给参数添加关键帧	"给ParamAngleX在0.5处添加一个关键帧"
DeleteParameterKey	ParameterId, KeyValue	删除参数关键帧	"删掉ParamAngleX在-30处的关键帧"
MoveParameterKey	ParameterId, OldKeyValue, NewKeyValue	移动关键帧位置	"把ParamAngleX的0.5关键帧移到0.8"
AddPart	Name, Id, ParentId	添加部件	"在'左眼'下新建部件'瞳孔'"
EditPart	Id, Name, LabelColorType, LabelCustomColor, Opacity	编辑部件属性 ⚠️ 标签色用 LabelColorType+LabelCustomColor，不是 LabelColor	"把'眉毛'部件的标签色改成蓝色"
AddWarpDeformer	Name, Id, ParentId	添加弯曲变形器	"在'前发'下新建一个弯曲变形器"
AddRotationDeformer	Name, Id, ParentId	添加旋转变形器	"在'头部'下新建旋转变形器"
EditWarpDeformer	Id, Name, ...	编辑弯曲变形器属性	"把WarpDeformer「曲面2」重命名为'脸部'"
EditArtMesh	Id, Opacity, ...	编辑图形网格属性	"把ArtMesh「左眼高光」的不透明度改成50%"
EditGlue	Id, ...	编辑胶水属性	"调整胶水对象的权重"
DeleteObject	Id	从部件面板删除对象	"删除ID为Warp999的对象"
MoveObjectOnPartsPalette	Id, NewParentId, InsertPosition	移动对象在部件面板中的位置	"把WarpDeformer「曲面2」移动到位置0"

常见问题

症状	原因	解决
MCP 状态红色	Python 路径/依赖/cwd 错误	检查 Python 版本 ≥ 3.10，确认依赖安装、cwd 路径正确
未连接到 Editor	Editor 未启动或外部集成未开启	启动 Editor → 加载模型 → 文件菜单开启外部集成
未授权	弹窗未勾选 Allow	在外部集成对话框中勾选 Allow
编辑报错	弹窗未勾选 Edit	在外部集成对话框中勾选 Edit
重启后失效	Editor 重启需重新授权	重新开启外部集成并勾选权限
操作报错	参数/ID 不正确	先用 cubism_get_*_structure 查询结构再操作

开发

# 直接运行测试
python cubism_mcp.py

# 依赖
pip install -r requirements.txt

依赖

包	用途
mcp	MCP 服务端框架（FastMCP + stdio 通信）
websockets	WebSocket 客户端，连接 Editor API

注意事项

• Alpha 版本限制：Cubism Editor 5.4 Alpha 有效期至 2026-09-14，到期后需升级
• 重启授权：每次重启 Editor 都需要重新开启外部应用集成并勾选权限
• 单模型：MCP 服务同时只能操作一个打开的模型
• 事务安全：编辑操作自动包裹 EditBegin/EditEnd，批量操作失败自动 Cancel 回滚

License

MIT