How do I use Cubism External Edit MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cubism External Edit MCP Show me the parameter structure of the model" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Cubism External Edit MCP

by nana7chi

Overview Schema Related Servers Score Discussions

Python

Local

Cubism External Edit MCP

Cubism Editor Python MCP MCP Badge

License GitHub stars GitHub last commit

中文 | 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"
    }
  }
}

方式二：本地克隆运行

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

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

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

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

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

启动 Cubism Editor 5.4 Alpha，打开一个模型
菜单「文件」→「外部应用程序集成的设置」
确认端口为 22033，打开「使用」开关
弹出授权对话框，找到 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

This server cannot be installed

license - not tested

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/nana7chi/CubismExternalEditMCP'

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