mcp-vroid

MCP‑сервер, который управляет графическим интерфейсом VRoid Studio. Он даёт любому MCP‑клиенту (Claude Code или чему угодно, что говорит по этому протоколу) набор инструментов для запуска приложения, просмотра изображения, поиска виджетов на картинке, кликов, ввода текста, установки параметров и экспорта в .vrm — на Arch + Hyprland (Wayland), при этом VRoid Studio запускается через Steam/Proton.

В VRoid Studio нет скриптового API, поэтому это работает единственным доступным способом: снимок окна, поиск объектов через OCR и сопоставление цветов, затем инъекция настоящих событий мыши и клавиатуры.

   grim ──► PNG ──► tesseract / cv2 ──► (x, y) ──► virtual pointer / XTEST
    ▲                                                        │
    └────────────────────  screenshot again  ◄───────────────┘

Движок под сервером — это набросок tools/vroid-driver из проекта arrakis, подключённый сюда как mcp_vroid.driver. Тот же код, переупакованный так, чтобы его было удобно устанавливать и запускать через MCP‑клиент.

Требования

Python‑зависимости (устанавливает uv sync): mcp, pillow, numpy, opencv-python-headless, pytesseract, python-xlib.

Related MCP server: blockout-mcp

Установка

git clone https://github.com/nhodges/mcp-vroid
cd mcp-vroid
uv sync                 # virtualenv + dependencies
bash native/build.sh    # builds native/vpointer  <-- REQUIRED, not optional

native/build.sh компилирует C‑клиент примерно на 150 строк для протокола zwlr_virtual_pointer_unstable_v1 (XML протокола подключён в native/protocols/). Без него каждый инструмент указателя завершится ошибкой native/vpointer missing. vroid_status сообщает, есть ли он.

Почему C‑помощник: ydotool не установлен на эталонной машине, а /dev/uinput имеет права 0600 root:root, поэтому evdev‑инъекция потребовала бы sudo или правила udev. Протокол виртуального указателя Wayland не требует ни того, ни другого, двигает реальный курсор композитора и работает поверх любого окна.

Регистрация у клиента

Claude Code:

claude mcp add vroid -- uv run --directory /path/to/mcp-vroid mcp-vroid

Обычный JSON mcpServers:

{
  "mcpServers": {
    "vroid": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-vroid", "mcp-vroid"]
    }
  }
}

Клиенты часто запускают серверы в очищенном окружении. Этот сервер при старте возвращает XDG_RUNTIME_DIR, WAYLAND_DISPLAY, HYPRLAND_INSTANCE_SIGNATURE и DISPLAY из каталога рантайма (src/mcp_vroid/session_env.py), поэтому hyprctl/grim/XTEST работают в любом случае; vroid_status показывает, что ему пришлось дозаполнить. Всё, что уже есть в окружении, выигрывает.

Опциональные переменные окружения:

Инструменты

Жизненный цикл

Наблюдение

Действия (низкоуровневый ввод)

Действия (сценарии)

Каждый инструмент‑действие сначала фокусирует VRoid и отказывается действовать, если активное окно — не VRoid Studio.

Как им пользоваться

В основе: снимок → смотрим → находим → действуем → снова снимок.

1. vroid_launch()

2. vroid_screenshot() и смотрим на картинку

3. vroid_find_text("Export") (или vroid_find_button()) — для координат

4. vroid_click(x, y) — координаты только из свежей картинки

5. vroid_screenshot(), чтобы проверить, что реально произошло

Эмпирические правила, которые были выработаны сложным путём в оригинале:

• Читайте весь кадр, а не обрезок. Модел окно подтверждения «Close Hairstyle Editor» стояло в центре экрана при шести неудачных кликах, потому что проверка искала только верхние 60 px.

• Не судите об изменениях по 3D‑вьюпорту. VRoid делает дизеринг буквально каждого кадра, поэтому сравнение полных кадров даёт дельту — а она равна ~0.98 даже когда ничего не происходило. Смотрите на полосу интерфейса.

• Числовые поля лучше, чем перетаскивание слайдера. vroid_set_slider вводит точное значение; для перетаскивания — только контролы без числового поля.

• Первичные кнопки ищут по цвету, а не по тексту. Серый цвет лепестки вместо синего — это признак приложения, что обязательная строка как бы пуста.

• Книга OCR всего кадра 2560×1440 занимает ~10 с. Передавайте регион.

Пространства координат

Одндутся два пространства:

Инструменты по умолчанию принимают и возвращают пиксели изображения (space="image") и преобразуют их между системами, так что можно передавать результат vroid_find_text сразу в vroid_click. Если MCP_VROID_MAX_IMAGE_PX уменьшил картинку, которую вы видите, умножьте координаты, которые вы прочитали на ней, на значение, обратное множителю downscale — или просто используйте vroid_find_text, который всегда возвращает натуральные пиксели.

Карта интерфейса (VRoid Studio 2.14.0, English)

Координаты — это пиксели изображения на снимке 2560×1440 полноэкранного окна. Относитесь к ним как к подсказкам: инструменты определяют объекты через OCR чтобы полноценно.

Стартовый экран — карточка Create New + в точке ≈ (118, 218), подпись в (118, 328); New / Open сверху справа в (2439, 99) / (2495, 100); ниже сетка Sample Models. Create New открывает модальное окно «Select a base to start with» с подписями Fem (1199, 862) и Masc (1359, 862) — нажмите на миниатюру примерно в 100 px над подписью.

Редактор — строка вкладок на y ≈ 23: Face 97 · Hairstyle 198 · Body 302 · Outfit 392 · Accessories 509 · Look 622. Бургер-меню ☰ в (29, 23) → Save (Ctrl+S), Save As… (Ctrl+Shift+S), импорт/массовый экспорт, отмена/повтор, возврат к выбору модели — Escape не закрывает это меню, кликните в другом месте. Панель инструментов сверху справа: камера (2415, 23), поделиться/экспорт (2464, 23), кебаб-меню ⋮ (2512, 23). Левая вертикальная полоса иконок (x ≈ 24, первая иконка y ≈ 77, затем каждые ~48 px) — подкатегория текущей вкладки. Левая панель — сетка пресетов с Presets / Custom на y ≈ 120. Правая панель — Customize, затем Parameters.

Элементы правой панели

Параметры Body начинаются с Model's Height : 161.2 cm, далее Fem Height, Masc Height, Body Size, Head Size, Head Width, Head Tip (Y), Neck Length/Thickness/Width, Soften Collarbone, … Параметры Face: Eye Size X/Y, Eyes Position (X/Y), Rotate Eye Socket, Inner/Outer Eye Slant, Iris Size X/Y, Gaze (Y), … (~40 строк; инструменты прокрутят за вас).

Редактор волос — вкладка Hairstyle → на левой полосе значок волос → подраздел Custom → + Create New → правая панель Edit Hairstyle. Внутри: Add Freehand Hair Guides / Add Procedural Hair Guides, список Hair Groups, палитра инструментов на (330 / 365 / 398 / 432, 83), отмена/повтор в (76, 23) / (133, 23). При выходе сначала появится запрос: кнопка ✕ в (23, 23) открывает модальное окно Close Hairstyle Editor с Save as new item / Overwrite / Close without saving.

Export as VRM — значок поделиться (2464, 23) → Export as VRM → полноэкранная страница экспорта с синей кнопкой-пилюлей Export в ≈ (2412, 197) → модальное окно VRM Settings (по центру, примерно x 1000–1560, прокручивается): радиокнопки Export Format VRM1.0 / VRM0.0, Avatar Name — обязательное, Version, Creators — обязательное, поля copyright/contact/references, чекбоксы использования. Кнопка-пилюля Export остаётся серой и неактивной, пока не заполнены оба обязательных поля → диалог сохранения Wine (отдельное окно с заголовком Export): поле File name: при открытии получает фокус и выделенный текст, поэтому ввод полного пути Windows заменяет его, а Return активирует кнопку по умолчанию. Префикс Proton отображает Z:\ на /, поэтому /home/nuri/x соответствует Z:\home\nuri\x. **Не** нажимайте Save, найденную через OCR — подпись Save in: попадает под тот же шаблон.

Что может ломаться

• Вся навигация завязана на OCR. Мелкие, разрежённые или светлые надписи на тёмном фоне расщепляются или теряются (Export → E + xport). У иконок нет текста вообще — их якоря прописаны как доли окна и будут сдвигаться, если pixiv перекомпонует UI.

• Фиксированные якоря — это доли, калиброванные под 2560×1440 при масштабе 1.25. На другом мониторе их, возможно, придётся замерять заново.

• Модальные окна могут открываться за пределами области поиска и молча поглощать клики.

• Тайминги. Трёхмерный вьюпорт появляется через ~5 с после выбора основы; экспорт длится 5–30 с (тяжёлые модели — дольше).

• Диалог Wine — отдельное окно со своим классом и геометрией — там используйте vroid_shunchot(whole_screen=true).

• Язык. Эти шаблоны ожидают английский интерфейс. Если VRoid поднялся на японском, переключите его в кебаб-меню ⋮ → Settings → Language.

• Экранная заставка, уходящая в idle, может захватить сессию в середине работы. Защита отказывается печатать в ней и закрывает только это одно окно перед действием.

Примечание о безопасности

Этот сервер передаёт реальные события мыши и клавиатуры в ваш живой рабочий стол и делает снимки экрана. В этом его суть, и в этом же его вис.

• Снимки экрана могут захватить всё, что выведено на экран: whole_screen=true снимает всё, и они сохраняются на диск без шифрования.

• Клавиши нажатия уходят приложения, у которого фокус. Драйвер отказывается работать, если VRoid Studio не имеет фокуса, но скомпрометированный или невнимательный промпт может нажать в любую точку внутри VRoid Studio.

• vroid_launch(restart=true) завершает VRoid Studio и теряет все несохранённые изменения.

• Здесь нет изоляции и нет шага подтверждения.

Запускайте его вручную, на наблюдаемых вами сессии, и не оставляйте агента управлять им без присмотра. vroid_release() вернёт рабочий стол по завершении.

Разработка

uv run python scripts/smoke_test.py             # start the server, list tools, call vroid_status
uv run python scripts/smoke_test.py --screenshot # + one passive capture if VRoid is open
uv run vroid-driver shot                        # the original driver CLI, still here

vroid-driver (mcp_vroid.driver.cli) — интерфейс оболочки спайка: launch, shot, find, click, tab, slider, export, cam, apply-params, … — удобно для отладки без MCP-клиента в цепочке.

Авторы и лицензия

Драйвер (src/mcp_vroid/driver/, native/) начался как спайк tools/vroid-driver в моём проекте arrakis и включен сюда вместе с обёрткой MCP-сервера.

MIT — см. LICENSE.