vroid-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
vroid-mcp
An MCP server that lets Claude (Claude Code, Claude Desktop or any MCP client) drive VRoid Studio on Windows: open tabs, set body/face parameters, change colours, export a VRM with metadata, and check the exported file.
VRoid Studio has no API, CLI or plugin system, so this server works the way a person does. It looks at the window (screen capture + Windows OCR), uses the mouse and keyboard (SendInput), and checks every action (reads the value back, checks the exported file).

Tested with VRoid Studio 2.14.0 (standalone installer, Windows 11, English UI, UI scaling 100 %, Windows display scale 100 %, 1024×768 and 1280×800 windows). Other versions or layouts may need calibration.
Why it is more reliable than plain "look and click"
Verified actions |
|
Locale-safe numbers | VRoid parses typed numbers with the Windows locale: on an Italian or German system, typing |
No wrong matches | Labels are matched as whole rows ("Size" never matches "Head Size"). A label found in two places is reported as ambiguous instead of being guessed. |
Fast | Windows' built-in OCR finds a label in ~40 ms. Known widgets are cached and re-validated in ~0.3 ms. Fixed sleeps are replaced by "wait until the UI stops changing". |
Clear errors | When something is missing, the tool returns an annotated screenshot (search area in red, closest texts in orange), plus what it was looking for and a hint. |
Native dialogs via UI Automation | The Windows save dialog is filled through UIA automation IDs: no OCR, no mouse, and it works in any Windows language. |
ERROR: could not find 'Tail Length' on screen
Looking for: text 'Tail Length'
Search region (client px, l,t,r,b): (728, 50, 1024, 768)
Closest texts on screen: 'Apply color when editing' (0.38); 'Customize' (0.32); ...
Hint: Check the screenshot: the panel may need scrolling, another tab may be open, ...
vroid_set_slider goes further: it scrolls the whole panel and lists every parameter label of the current tab.
Related MCP server: mcp-vroid
Limitations (please read)
It is fragile by nature. It depends on VRoid's layout, labels and colours. A VRoid update can break it until the profile is updated or re-calibrated.
English UI only (Settings › Language › English in VRoid).
vroid_statuswarns if VRoid's language or UI scaling differs.It briefly takes the foreground. VRoid draws a blank white window while unfocused and ignores background (PostMessage) clicks. Each tool call therefore focuses VRoid, acts, and then restores your mouse position and the previously focused window. Don't type while a tool is running.
Windows only, one VRoid instance, one action at a time.
Not every feature has a high-level tool. The hair editor, texture painting and the Dress-up feature can be reached with the low-level tools (
vroid_screenshot,vroid_click_text,vroid_click, …), but nothing verifies those steps for you.The Steam version is detected and launched (
steam://rungameid/1486350) but has not been tested.Screenshots go to the MCP client (the model) and are not stored on disk.
Requirements
Windows 10 (1903+) or 11.
VRoid Studio 2.14.0 (standalone; Steam probably works too).
uv (it installs Python ≥ 3.11 for you).
A Windows OCR language. Any Latin-script language works (en-US, it-IT, fr-FR, …), and most Windows installs already have the one matching their display language. Check with
vroid_statusor the smoke test. To add English, run in an admin PowerShell:Add-WindowsCapability -Online -Name "Language.OCR~~~en-US~0.0.1.0"
Install
git clone https://github.com/Topogamer0/vroid-mcp.git
cd vroid-mcp
uv syncRegister with Claude Code
Use the absolute path of the folder you cloned:
claude mcp add vroid -- uv run --directory "C:\path\to\vroid-mcp" vroid-mcpIf VRoid is installed somewhere unusual, add environment variables:
claude mcp add vroid -e VROID_EXE="D:\Apps\VRoidStudio\VRoidStudio.exe" -- uv run --directory "C:\path\to\vroid-mcp" vroid-mcpOr run straight from GitHub without cloning:
claude mcp add vroid -- uvx --from git+https://github.com/Topogamer0/vroid-mcp vroid-mcpThen, in Claude Code, /mcp should list vroid with 15 tools.
{
"mcpServers": {
"vroid": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\vroid-mcp", "vroid-mcp"]
}
}
}Configuration
Variable | Default | Meaning |
| auto | Full path to |
|
| Where relative export paths go. |
|
| Longest edge of the screenshots sent to the model (JPEG). Lower it to save tokens. |
|
|
|
|
| UI profile to use. |
Tools
Tool | What it does |
| Install path, running state, version, window size, DPI, unsaved changes ( |
| Start VRoid if needed and wait for the start screen. Optional |
| Close VRoid. Refuses unless |
| Client area only, downscaled JPEG (~40 KB), plus the detected screen ( |
| OCR search. Returns boxes and centres in client and image pixels. |
| Click a point ( |
| Raw keyboard and wheel input. |
| Face, Hairstyle, Body, Outfit, Accessories or Look, verified. |
| Set a parameter by typing its value (never dragging), with scrolling, read-back and log evidence. |
| Set a |
| Full export: VRM 1.0 or 0.0, name, version, creators, Windows save dialog, wait for the file, back to the editor, parse the result. Refuses to overwrite without |
| Read any |
Examples
Things to ask Claude once the server is registered:
"Open VRoid, create a new feminine model, make the head 10 % smaller and the eyes a bit bigger, then export it as
small_head.vrmwith name Test and creator me.""On the Body tab set Fem Height to 0.3 and Leg Length to 0.2, then show me a screenshot."
"Set the skin Color to #F5DCCB."
"Export the current model as VRM 0.0 to
D:\avatars\alice.vrm, then check that it has all required humanoid bones.""Inspect
C:\Users\me\Downloads\model.vrm: which expressions and texture sizes does it have?"
A typical tool result:
{
"label": "Head Size", "requested": -0.2, "typed": "-0,200", "before": 0.0, "after": -0.2,
"verification": {"verified": true, "detail": "field reads '-0,200'"},
"log": [{"command": "SetBoneTransformParameterCommand",
"params": {"Level2Head_HeadScaleShrink": 0.2, "Level2Head_HeadScaleMag": 0.0}}]
}Safety
No destructive action without an explicit flag:
overwrite=true(exports),confirm=true(restart, close). The tool descriptions tell the model to ask you first.The server never saves or closes your project on its own, and never clicks "don't save".
It injects real mouse and keyboard input into your session, so use it attended, on your own machine.
Calibration
If a VRoid update moves icons, re-record them instead of waiting for a release:
uv run vroid-calibrate list # icons/anchors in the active profile
uv run vroid-calibrate check # which ones resolve on the current screen
uv run vroid-calibrate record export_share # hover the icon in VRoid, press Enter hereRecorded profiles go to %APPDATA%\vroid-mcp\profiles\ and override the bundled one. Text labels need no calibration, because they are found by OCR. PRs with profiles for new VRoid versions are welcome.
Development
uv sync
uv run pytest # 90+ tests, no VRoid needed (OCR tests need Windows OCR)
uv run python scripts/smoke_test.py # start the server over stdio, list tools, status
uv run python scripts/probe.py # environment probe (UIA, capture backends, OCR)
uv run python scripts/e2e_manual.py # real VRoid: new model > Head Size > export > inspectThe design notes and the measurements behind every choice are in docs/DESIGN.md.
src/vroid_mcp/
server.py MCP tools (stdio)
session.py focus / capture / input around each tool call
flows/ editor (tabs, sliders, colours), export, lifecycle
vision/ Windows OCR, label matching, locator (cache > OCR > template), imaging
win/ DPI + coordinates, window, capture (WGC/PrintWindow), SendInput, file dialogs
formats/vrm.py VRM 0.x/1.0 reader
profiles/ measured UI layout per VRoid versionCredits
Inspired by mcp-vroid by nhodges, the Linux/Wayland original. The tool names and the overall approach come from there. The Windows side, the verification layer and the matching were rewritten.
VRoid and VRoid Studio are trademarks of pixiv Inc. This project is not affiliated with or endorsed by pixiv. The screenshots of VRoid Studio in
docs/andtests/fixtures/show its user interface and are used only to document and test this tool.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Lets your AI build and edit websites in Xodia, a visual website builder for real code (Vite, React, Tailwind CSS or plain HTML in your own git repo): read and write site files, create pages and CMS collections, run typecheck, design and link checks, take screenshots, manage forms and translations, and pick up change requests the user sends from the visual editor. Sign in once with your Xodia account (OAuth). Free plan, no card needed. Setup: https://xodia.ai/ai/mcp
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to show, animate, and control a VRM character on the desktop, including posing and motion installation via MCP tools.1MIT
- AlicenseAqualityDmaintenanceEnables MCP clients to drive VRoid Studio's GUI by launching the app, capturing screenshots, locating UI elements via OCR/color, and simulating clicks/typing to adjust parameters and export .vrm files.189MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients on Windows to control the local mouse, keyboard, and screen understanding via MCP stdio, allowing automated workflows like viewing the screen, locating elements, clicking, typing, and verifying results.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables controlling VRoid Studio through desktop GUI automation, letting an MCP client launch the app, capture its window, locate controls via OCR, edit character parameters, and run save/export flows on macOS and Linux/Hyprland.MIT