vroid-files MCP server

This MCP server reads and patches VRoid Studio 2.x .vroid files directly. VRoid has no API or plugin system, so the server works on the files, not on the running app. Edit with the server, then open the new file in VRoid to see the result.

• Every write creates a new .vroid file. The source is never changed.

• Each write is checked before it is saved: same parameters, same value entries, same textures.

Tools

Related MCP server: mcp-vroid

Status

Unofficial and not affiliated with VRoid or pixiv. The file format has no public spec; it was worked out from files saved by VRoid Studio 2.14 (see File format below). Other 2.x versions will probably work but are not tested. Keep a backup of your models. The server never changes a source file, but VRoid may refuse a file it does not like.

Setup

You need Python 3.10 or newer.

Quickest: run it with uv

With uv installed, your MCP client can start the server straight from GitHub, with nothing to clone:

{
  "mcpServers": {
    "vroid-files": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/JAmadoD/vroid-files-mcp", "vroid-files-mcp"],
      "env": { "VROID_ALLOWED_ROOTS": "C:\\Users\\you\\Documents\\VRoid" }
    }
  }
}

Or: clone and install

Windows:

git clone https://github.com/JAmadoD/vroid-files-mcp
cd vroid-files-mcp
python -m venv .venv
.venv\Scripts\python -m pip install .

Mac and Linux:

git clone https://github.com/JAmadoD/vroid-files-mcp
cd vroid-files-mcp
python3 -m venv .venv
.venv/bin/python -m pip install .

This installs a vroid-files-mcp command into the venv (.venv\Scripts\vroid-files-mcp.exe on Windows, .venv/bin/vroid-files-mcp on Mac and Linux). Running python server.py from the checkout also works.

Register it with your MCP client

The server speaks MCP over stdio. Use the full path to the command from the step above.

Claude Code (from a terminal):

claude mcp add vroid-files -e VROID_ALLOWED_ROOTS=C:\Users\you\Documents\VRoid -- C:\path\to\vroid-files-mcp\.venv\Scripts\vroid-files-mcp.exe

Claude Desktop, Cursor, VS Code and other clients take the same JSON shape in their MCP settings file (for Claude Desktop that is claude_desktop_config.json; for a project it is often .mcp.json):

{
  "mcpServers": {
    "vroid-files": {
      "command": "C:\\path\\to\\vroid-files-mcp\\.venv\\Scripts\\vroid-files-mcp.exe",
      "env": { "VROID_ALLOWED_ROOTS": "C:\\Users\\you\\Documents\\VRoid" }
    }
  }
}

Settings (environment variables)

Set VROID_ALLOWED_ROOTS first. Without it, the server accepts any absolute path your MCP client sends.

Safety rules built in

• Every write creates a new .vroid file. The source is never changed, and an existing file is never replaced.

• Exports only write .png files and never replace an existing file unless overwrite is true.

• Each write is re-read and checked before it is kept.

Typical loop

1. Put the garment on in VRoid and save the file.

2. Run vroid_list_textures with compare_to set to the model without the garment. This shows the new garment's layers.

3. Export a layer and edit the PNG at the same size.

4. Replace the layer into a new file.

5. Change colours or sliders with vroid_set_item_colors or vroid_set_params.

6. Open the new file in VRoid: model selection screen, then Open.

File format (found on VRoid 2.14 files)

• Zip contents: meta.json, v1model/meta.json, v1model/data.bin (protobuf, no public schema) and thumbnails/thumbnail.jpg.

• Texture entry: {1 id (40 hex), 6 {1 width, 2 height, 3 {1 layer...}}}.

• Layer: {1 guid, 2 name, 7 {2 PNG}}.

• Texture IDs: not hashes of the image, so a PNG can be swapped and the ID kept.

• Recipe parameters: top-level field 5, one message per part. Each parameter is {1 name, K {1 value_id or literal}}, where K is 3 choice, 4 colour, 5 slider, 6 image, 7 flag, 8 number or 9 template.

• Values: stored in each part's record as entries {1 value_id, 2 '', 3 value}. Record field 2 holds colours ({1 r, 2 g, 3 b, 4 a} floats), field 3 numbers (sliders use the number shown in VRoid), field 9 flags (varint).

• Zero values are left out. A slider at 0 is an entry with no field 3. Writes rebuild the whole entry in place. Appending a second entry with the same id makes VRoid refuse the file.

• Not mapped yet: item thumbnails, adding new layers, and adding or removing garments (pick those in VRoid, then tune them here).

Verified in VRoid 2.14

• A recoloured clothing layer and a changed shade colour open and show correctly.

• A slider stored as a default (jacket Sleeve (Shorter), 0 to 100) loads, shows 100 in the panel and shortens the sleeve.

Tests

The tests use your own files, read-only, and skip when they are not set:

set VROID_TEST_BASE=C:\path\to\model.vroid
set VROID_TEST_OUTFIT=C:\path\to\model_with_jacket.vroid
.venv\Scripts\python -m unittest test_vroidfile -v

On Mac and Linux, use export VROID_TEST_BASE=... and .venv/bin/python.

The outfit file should wear a top made of at least two templates (for example shirt and jacket). VROID_TEST_TMP sets the folder for temporary output.

Command-line helper

client.py calls the server the same way an MCP client does, which is handy for scripts and quick checks. Put the tool arguments in a JSON file:

python client.py list
python client.py vroid_info @args.json

where args.json holds, for example, {"path": "C:\\models\\my_model.vroid"}.

License

Free and source available under the AmadOpenSource License 1.0 (see LICENSE). In short: you may use it for anything, including in your business and to make money, and anything you make with it is yours. You may not sell the software itself, charge others to use or host it, or turn it into a paid or closed product. Free changed versions are welcome if they keep this license, publish their full source and credit "Based on vroid-files-mcp by Joshua Amado".

Contributions are welcome; see CONTRIBUTING.md.