Control Virt-A-Mate from any MCP client (Claude Code, Codex, Cursor, Claude Desktop, …) in plain language: build scenes, add atoms, sculpt morphs, swap looks/clothing/hair, pose characters, drive expressions and bones, tweak any parameter, move the camera and take screenshots, browse and download Hub content, manage VaM plugins, and more.
The MCP server runs inside the BepInEx plugin, in the VaM process, over Streamable HTTP
(spec 2025-06-18). Your agent connects straight to http://127.0.0.1:9837/mcp — no Python,
no side-car process, no file polling.
MCP client ──HTTP/JSON-RPC──▶ VaMMCP (BepInEx plugin, inside the VaM process)
├─ background thread: tiny HTTP server (loopback-only, Origin-checked)
├─ JSON-RPC / MCP layer (initialize / tools/list / tools/call / resources)
├─ main-thread dispatcher (queue → Unity Update)
└─ VaM control layer (SuperController / Atom / JSONStorable / DAZMorph / MVRPlugin …)
⚠️ Unofficial community project. Not affiliated with, endorsed by, or connected to Meshed VR, Virt-A-Mate or the VaM Hub. Use it only with a copy of VaM you legally own, and respect the VaM EULA and the licence of any Hub content you download.
| Category | Tools |
|---|---|
| Status | status |
| Scene | list_scenes load_scene new_scene save_scene |
| Atom | list_atom_types list_atoms add_atom remove_atom set_atom_on get_atom_transform set_atom_transform |
| Person | add_person list_persons list_looks load_look save_look set_character |
| Preset export | save_look (appearance incl. clothing/hair) save_pose save_full_preset |
| Morphs | list_morphs set_morph get_morph reset_morphs |
| Clothing / hair | list_packages list_clothing_presets (scans disk + every .var package) load_clothing_preset list_clothing_items add_clothing_item remove_clothing_item set_clothing_item_on list_hair_presets load_hair_preset list_hair_items add_hair_item remove_hair_item set_hair_item_on |
| Pose / expression | list_poses load_pose save_pose list_expressions set_expression |
| Bone control | list_controls get_control set_control set_gaze |
| Generic parameters (long tail) | list_atom_storables list_storable_params get_param set_param call_action |
| Camera | get_camera set_camera capture_view |
| Simulation | set_simulation reset_simulation |
| Hub | hub_browse hub_detail hub_download |
| Skin | set_skin_sss (subdermis colour) |
| Plugins | list_plugins add_plugin remove_plugin |
| Escape hatch (off by default) | eval_cs |
Full reference: docs/TOOLS.md.
Design note: every slider in the VaM UI is ultimately a JSONStorable parameter — enumerate
with list_storable_params, write with set_param. That is where the "covers everything"
claim comes from. Morphs are the heart of character sculpting (DAZMorph.morphValue), and a
loaded VaM plugin simply becomes another storable on the atom, so the generic layer reaches it too.
- Virt-A-Mate 1.20+ (developed against 1.22.0.13 / Unity 2018.1.9f2 / Mono)
- BepInEx 5.4.x (x64) installed in the VaM folder (
winhttp.dll+BepInEx/) - An MCP client that speaks Streamable HTTP
Building from source additionally needs the .NET SDK. The plugin targets net35 because VaM runs at the .NET 3.5 API level.
- Install BepInEx 5.4.21 x64 into your VaM folder if you have not already
(download → unzip into the folder
containing
VaM.exe→ launch VaM once so BepInEx creates its directories). - Download
VaMMCP.dllfrom the latest release. - Drop it into
<VaM>\BepInEx\plugins\. - Start VaM.
<VaM>\BepInEx\LogOutput.logshould containVaMMCP ready. MCP endpoint: http://127.0.0.1:9837/mcp.
Run in the VaM folder; it installs BepInEx if missing and fetches the latest VaMMCP release:
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
# or point it somewhere else:
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -VamRoot "D:\VaM"./scripts/install-bepinex.sh # only if BepInEx is not installed yet
./scripts/deploy.sh # build + copy to <VaM>/BepInEx/plugins/VaMMCP.dllBoth scripts assume the repo sits inside the VaM folder. Otherwise point them at it:
export VAM_ROOT="D:/path/to/VaM" # read by the scripts
# or: dotnet build src/VaMMCP.csproj -c Release -p:VaMRoot=D:/path/to/VaMWith VaM running:
{
"mcpServers": {
"vam": {
"type": "http",
"url": "http://127.0.0.1:9837/mcp"
}
}
}claude mcp add vam --transport http http://127.0.0.1:9837/mcp
codex mcp add vam --transport http http://127.0.0.1:9837/mcpPer-client instructions: docs/clients.md. Smoke test: ./scripts/smoke-test.sh.
| Key | Default | Meaning |
|---|---|---|
| Server.Enabled | true | Start the MCP server when VaM launches |
| Server.Port | 9837 | Listening port (bound to 127.0.0.1 only) |
| Security.AllowEval | false | Expose eval_cs (runs arbitrary C# in-process — dangerous) |
| Security.EvalTimeoutSec | 30 | eval_cs timeout in seconds |
The file appears after the first launch with the plugin installed.
src/
├── Plugin.cs # BepInEx entry point, config, main-thread pump
├── MainThread.cs # HTTP thread → Unity main thread dispatcher (blocking)
├── Util.cs # logging / ApiError
├── Mcp/
│ ├── HttpServer.cs # minimal HTTP/1.1 server (Streamable HTTP, Origin check, keep-alive)
│ ├── McpServer.cs # MCP protocol: initialize / tools/list / tools/call / resources
│ ├── Tool.cs # tool definition (name / description / JSON schema / handler / timeout)
│ └── ToolRegistry.cs # all 63 tool registrations
└── Api/
└── VaMApi.cs # VaM control layer (every tool implementation)
See docs/DEVELOPMENT.md for build details, threading rules and a long list of VaM-specific pitfalls. Contributions welcome — CONTRIBUTING.md.
- The HTTP server binds to
127.0.0.1only and validates theOriginheader (DNS-rebinding protection). There is no authentication: anything that can reach loopback on your machine can drive VaM. Treat it like any other local dev server. eval_csis disabled by default. Enabling it gives your agent arbitrary code execution inside the VaM process (still subject to VaM's runtime sandbox: System.IO, System.Reflection, System.AppDomain, UnityEditor and Mono.Cecil are blocked).- Hub downloads are subject to Hub content licences; paid content requires you to be signed into your Hub account inside VaM.
Reporting a vulnerability: SECURITY.md.
MIT. Provided "as is", without warranty or liability of any kind.