Cubism External Edit MCP

中文 | English

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

官方参考文档：Cubism Editor 外部应用集成 API

架构

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

功能特性

• 完整模型查询 — 参数结构、部件结构、变形器结构、单个对象详情
• 编辑操作 — 增删改查参数/部件/变形器/ArtMesh/Glue，自动事务包裹
• 批量编辑 — 同一事务内执行多个操作，任一失败自动回滚
• 权限分级 — 查询需 Allow 授权，编辑需 Edit 授权
• 自动重连 — Editor 重启后自动重连，3 秒间隔
• Token 持久化 — 认证令牌缓存到 token.txt，避免重复授权

环境要求

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

配置 MCP 客户端

也支持ClaudeCode, Codex, OpenCode等其他支持MCP的客户端

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

在 Workbuddy 中设置 → MCP → 添加 编辑JSON，在mcpServers中添加cubism-mcp：

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

方式二：本地克隆运行

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

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

2. 在 Workbuddy 中设置 → MCP → 添加 编辑JSON，在mcpServers中添加cubism-mcp（修改 cwd 为实际路径）：

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

使用流程

1. AI Agent配置MCP客户端，
   • 第一次配置启动需要下载依赖包，花费时间较久
2. 启动 Cubism Editor，加载模型
3. 文件 → 外部应用集成设置 → 端口 22033 → 开启
4. 弹出对话框勾选 Allow + Edit，确认
5. 在 AI Agent 中通过自然语言操控 Editor

使用示例（提示词）

"列出当前模型的参数结构"
"查看部件层级"
"把 Core 部件的标签设为蓝色"
"新建参数 ParamsTest，ID 为 ParamTest，范围 0-1，默认 0.5"
"批量添加 3 个关键帧到 ParamAngleX"
"选中整体XY 变形器，移动到位置 (3000, 4000)"

可用工具

诊断

工具	说明
cubism_status	检查连接状态、注册状态、授权状态、编辑授权

查询

工具	参数	说明
cubism_get_model_uid	—	获取当前打开模型的 UID
cubism_get_parameter_structure	model_uid	参数结构树（组+参数，含 Min/Default/Max）
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	获取 Editor 中当前选中的对象列表

编辑

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

支持的编辑 Action

AddParameter, EditParameter, DeleteParameter, AddParameterGroup, EditParameterGroup, AddPart, EditPart, AddWarpDeformer, AddRotationDeformer, EditWarpDeformer, EditArtMesh, EditGlue, MoveParameter, MoveParameterGroup, AddParameterKey, DeleteParameterKey, MoveParameterKey, DeleteObject, MoveObjectOnPartsPalette

常见问题

症状	原因	解决
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 服务端框架（stdio 通信）
websockets	WebSocket 客户端，连接 Editor API
pydantic	数据模型验证
nest_asyncio	嵌套事件循环支持

注意事项

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

License

MIT