Content
# Cubism External Edit MCP
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[English](README_EN.md)
Encapsulate the external application integration API of Live2D Cubism Editor into **MCP (Model Context Protocol)** tools, allowing AI Agents (such as Workbuddy) to control Cubism Editor through natural language for modeling operations.
> Official reference documentation: [Cubism Editor External Application Integration API](https://cubism.live2d.com/editor-alpha/doc/manual/alpha1/en/external-api-intergration/index.html)
## Architecture
```
AI Agent (Workbuddy)
│
│ stdio (MCP Protocol)
│
┌───▼──────────────────────┐
│ cubism_mcp_server.py │ ← This project
│ (MCP Server, 9 Tools) │
└───┬──────────────────────┘
│
│ WebSocket (ws://localhost:22033)
│
┌───▼──────────────────────┐
│ Cubism Editor 5.4 Alpha │
│ (External Application Integration API) │
└──────────────────────────┘
```
## Features
- **Complete Model Query** — Parameter structure, part structure, deformer structure, single object details
- **Editing Operations** — Add, delete, modify, and query parameters/parts/deformers/ArtMesh/Glue, automatically wrapped in transactions
- **Batch Editing** — Execute multiple operations within the same transaction, automatically rolled back if any fail
- **Permission Grading** — Query requires Allow authorization, editing requires Edit authorization
- **Automatic Reconnection** — Editor restarts automatically reconnect, with a 3-second interval
- **Token Persistence** — Authentication token cached in `token.txt`, avoiding repeated authorization
## Environment Requirements
| Component | Version |
|------|------|
| Python | ≥ 3.10 |
| Cubism Editor | 5.4 Alpha (valid until 2026-09-14) |
| Operating System | Windows / macOS |
## Configuring MCP Client
> Also supports other MCP clients like ClaudeCode, Codex, OpenCode, etc.
### Method 1: uvx Online Running (Recommended)
In Workbuddy, go to Settings → MCP → Add JSON, and add `cubism-editor` in `mcpServers`:
```json
{
"mcpServers": {
"cubism-editor": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/nana7chi/CubismExternalEditMCP.git", "cubism-mcp"],
"description": "Cubism Editor MCP"
}
}
}
```
### Method 2: Local Clone and Run
1. Clone the source code to local:
```bash
git clone https://github.com/nana7chi/CubismExternalEditMCP.git
```
2. In Workbuddy, go to Settings → MCP → Add JSON, and add `cubism-editor` in `mcpServers` (modify `cwd` to actual path):
```json
{
"mcpServers": {
"cubism-editor": {
"type": "stdio",
"command": "python",
"args": ["cubism_mcp_server.py"],
"cwd": "J:/Modify to actual path/CubismExternalEditMCP"
"description": "Cubism Editor MCP"
}
}
}
```
## Usage Process
1. Launch Cubism Editor, load the model
2. **File → External Application Integration Settings** → Port `22033` → Enable
3. Pop-up dialog, check **Allow + Edit**, confirm
4. Control Editor through natural language in AI Agent
## Available Tools
### Diagnosis
| Tool | Description |
|------|------|
| `cubism_status` | Check connection status, registration status, authorization status, editing authorization |
### Query
| Tool | Parameters | Description |
|------|------|------|
| `cubism_get_model_uid` | — | Get the UID of the currently open model |
| `cubism_get_parameter_structure` | `model_uid` | Parameter structure tree (group + parameter, with Min/Default/Max) |
| `cubism_get_part_structure` | `model_uid` | Part structure tree (ArtMesh/Deformer/Part/Glue) |
| `cubism_get_deformer_structure` | `model_uid` | Deformer structure tree |
| `cubism_get_object` | `model_uid`, `id` | Get the details of a specified object (returns different structures by type) |
| `cubism_get_selected` | `model_uid` | Get the list of currently selected objects in Editor |
### Editing
| Tool | Parameters | Description |
|------|------|------|
| `cubism_edit` | `action`, `params` | Execute a single editing operation (automatically Begin/End) |
| `cubism_edit_batch` | `actions[]` | Batch editing (same transaction, automatically rolled back if any fail) |
#### Supported Editing Actions
`AddParameter`, `EditParameter`, `DeleteParameter`, `AddParameterGroup`, `EditParameterGroup`, `AddPart`, `EditPart`, `AddWarpDeformer`, `AddRotationDeformer`, `EditWarpDeformer`, `EditArtMesh`, `EditGlue`, `MoveParameter`, `MoveParameterGroup`, `AddParameterKey`, `DeleteParameterKey`, `MoveParameterKey`, `DeleteObject`, `MoveObjectOnPartsPalette`
## Usage Examples
```
"List the parameter structure of the current model"
"View the part hierarchy"
"Set the label of the Core part to blue"
"Create a new parameter ParamsTest, ID ParamTest, range 0-1, default 0.5"
"Batch add 3 keyframes to ParamAngleX"
"Select the whole XY deformer, move to position (3000, 4000)"
```
## Frequently Asked Questions
| Symptom | Cause | Solution |
|------|------|------|
| MCP status red | Python path/dependency/`cwd` error | Check Python version ≤ 3.13, confirm dependency installation, `cwd` path correct |
| Not connected to Editor | Editor not launched or external integration not enabled | Launch Editor → Load model → Enable external integration from File menu |
| Not authorized | Pop-up dialog not checked Allow | Check Allow in external integration dialog |
| Editing error | Pop-up dialog not checked Edit | Check Edit in external integration dialog |
| Invalid after restart | Editor restart requires re-authorization | Re-enable external integration and check permissions |
| Operation error | Parameter/ID incorrect | Use `cubism_get_*_structure` to query structure before operation |
## Development
```bash
# Run test directly
python cubism_mcp_server.py
# Dependencies
pip install -r requirements.txt
```
### Dependencies
| Package | Purpose |
|----|------|
| `mcp` | MCP server framework (stdio communication) |
| `websockets` | WebSocket client, connect to Editor API |
| `pydantic` | Data model validation |
| `nest_asyncio` | Nested event loop support |
## Notes
- **Alpha version limitation**: Cubism Editor 5.4 Alpha valid until 2026-09-14, need to upgrade after expiration
- **Restart authorization**: Each Editor restart requires re-enabling external application integration and checking permissions
- **Single model**: MCP service can only operate on one opened model at a time
- **Transaction safety**: Editing operations automatically wrapped in `EditBegin/EditEnd`, batch operations automatically rolled back if any fail
## License
MIT
