mcp-vroid

Ein MCP-Server, der die GUI von VRoid Studio steuert. Er stellt jedem MCP-Client (Claude Code oder allem anderen, das das Protokoll spricht) einen Satz Tools zur Verfügung, um die App zu starten, sie anzusehen, Widgets im Bild zu finden, zu klicken und zu tippen, Parameter zu setzen und eine .vrm zu exportieren – auf Arch + Hyprland (Wayland), wobei VRoid Studio unter Steam/Proton läuft.

Es gibt keine Skripting-API in VRoid Studio, daher funktioniert das nur auf die einzige verfügbare Weise: Das Fenster zuschneiden, Dinge mit OCR und Farbabgleich lokalisieren und echte Zeiger- und Tastaturfunktionen autorengen.

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

Die Basis des Servers ist die tools/vroid-driver-Spike aus meinem arrakis-Projekt, hier eingefügt als mcp_vroid.driver – gleicher Code, neu verpackt, sodass er von einem MCP-Client installiert und gestartet werden kann.

Anforderungen

Python-Abhängigkeiten (uv sync installiert sie): mcp, pillow, numpy, opencv-python-headless, pytesseract, python-xlib.

Related MCP server: blockout-mcp

Installation

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 kompiliert einen \~150-Zeilen-C-Client für zwlr_virtual_pointer_unstable_v1 (das Protokoll-XML liegt unter native/protocols/). Ohne ihn schlagen alle Zeiger-Werkzeuge mit native/vpointer fehlt fehl. vroid_status gibt an, ob er vorhanden ist.

Warum ein C-Helfer: ydotool ist auf der Referenzmaschine nicht installiert und /dev/uinput ist 0600 root:root, sodass evdev-Einspritzung sudo oder eine udev-Regel erfordern würde. Das Wayland-Virtual-Pointer-Protokoll braucht keins von beidem, bewegt den echten Cursor des Compositors und funktioniert über jedem Fenster.

Bei einem Client registrieren

Claude Code:

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

Allgemeines mcpServers-JSON:

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

Clients starten Server oft mit einer bereinigten Umgebung. Dieser Server stellt XDG_RUNTIME_DIR, WAYLAND_DISPLAY, HYPRLAND_INSTANCE_SIGNATURE und DISPLAY beim Start aus dem Laufzeitverzeichnis wieder her (src/mcp_vroid/session_env.py), sodass hyprctl/grim/XTEST trotzdem funktionieren; vroid_status zeigt, was ergänzt werden musste. Was in der Umgebung bereits vorhanden ist, hat Priorität.

Optionale Umgebungsvariablen:

Tools

Lifecycle

Sehen

UEben (Roher Eingang)

Ebenenden: (Abnläufe)

Jedes Aktions-Tool fokussiert zuerst VRoid und verweigert die Aktion, wenn nicht VRoid Studio das aktive Fenster ist.

So treibt man es

Meist so: Bildschirmfoto → anschauen → Position finden → Akt auslösen → wieder

1. vroid_launch()

2. vroid_screenshot() und den Bild ans mal

3. vroid_find_text("Export") (oder alternativ vroid_find_button()) für Koordinaten

4. vroid_click(x, y) – Koordinaten immer von einem neuen Bild,

5. vroid_screenshot(), um Sicherung zu bekommen, was wirklich passiert ist.

Praxisregeln, die man aus der ursprünglich leicht unbekannt ins Om erkundet hat:

• Den Glaube, ${», – ** lies Insgesamt, nicht den Ausschnitt.** Ein „Close Hairstyle Editor"-Dialog hing deutlich in der Bildschirmmit bisher 6 gescheiterte Transaktionen, weil die Prüfung nur die oberen 60 Pixel las.

• Schließe nicht aus Änderungen im 3D-View. VRoid flackt/verwirbelt jedes Bild, ein Vollabdruck wird ungefähr ~8.98 . Und selbst, wenn nichts geschehen ist etwas, sehen Sie nur VVI.

• Über NUM extrem besser ... Numerische Eingabefelder statt Schieberegler. vroid_set_slider tippt den exakteEARL, – ziehen für öffnete Elemente.

• Beurteile nächte per „„primary“ massbes beurteilen; statt mit dem Text. blau statt graue Pille heißt: Pflichtfeld ist noch nicht gesetzt..

• OCR eines komplett 2560×1440-Bildes braucht um "~10 Sekunden. Übergib eines region müssen.

Koordinatenräume

Alle drei Maßsysteme sind beteiligt und unterscheiden sich:

Die Tools erhalten und ausgeben standardmäßig Bildpixel (space="image") und konvertieren das intern – also . dato die von vroid_find_text` gemeldete Mitten directly pass on to vroid click. Wenn du später mit nek lang Returns*, multiplicate man die + sind “ we can get = from, pink {@ ...

In Hdd: , after female *" Females maintain with straight face. When the MAX_IMAGE_PX person resized See Image No“.

– Normally, (o-V)

TT. Prior → Exit -per long etc. command ihre Platz["schwellen".

If sich etc. the Kob. Adjust«."

… [marginal]

UI-Referenz (VRoid 2.14.0e)

Angießt sind image px auf einem 2560×1440 Screenshot vom Vollbild. Behandeln Sie diese als grobe Orientierung – die Orte locking via vroid_find_text first.;

Also die. put.notes away.

Startbildschirm — Create New-Karte mit + bei ≈ (118, 218), Beschriftung bei (118, 328); New / Open oben rechts bei (2439, 99) / (2495, 100); darunter das „Sample Models“-Raster. „Create New“ öffnet ein modales Fenster mit dem Titel „Wähle eine Basis zum Starten“ und den Bildunterschriften Fem (1199, 862) und Masc (1359, 862) — klicken Sie die Miniaturansicht etwa 100 px über der Bildunterschrift.

Editor — Registerleiste bei y ≈ 23: Face 97 · Hairstyle 198 · Body 302 · Outfit 392 · Accessories 509 · Look 622. Hamburger-Menü ☰ bei (29, 23) → Speichern (Ctrl+S), Speichern unter… (Ctrl+Shift+S), Import/Massenexport, Rückgängig/Wiederholen, zurück zur Modellauswahl — Escape schließt dieses Menü nicht, klicken Sie stattdessen woanders hin. Werkzeugleiste oben rechts: Kamera (2415, 23), Teilen/Export (2464, 23), Kebab-Menü ⋮ (2512, 23). Linke Symbolleiste (x ≈ 24, erstes Symbol bei y ≈ 77, dann alle ca. 48 px) = Unterkategorie des aktuellen Tabs. Linkes Panel = Preset-Raster mit Presets/Custom bei y ≈ 120. Rechtes Panel = Anpassen, dann Parameter.

Steuerelemente des rechten Panels

Die Body-Parameter beginnen mit Model's Height : 161.2 cm, danach folgen Fem Height, Masc Height, Body Size, Head Size, Head Width, Head Tip (Y), Neck Length/Thickness/Width, Soften Collarbone, … Die Face-Parameter: Eye Size X/Y, Eyes Position (X/Y), Rotate Eye Socket, Inner/Outer Eye , ... (ca. 40 Zeilen; die Werkzeuge scrollen sie für Sie).

Haar-Editor — Hairstyle-Tab → linkes Leisten-Symbol → Untertab Custom → + Create New → rechtes Panel Edit Hairstyle. Im Inneren: Add Freehand Hair Guides / Add Procedural Hair Guides, eine Hair Groups-Liste, eine Werkzeugpalette bei (330 / 365 / 398 / 432, 83), Rückgängig/Wiederholen bei (76, 23) / (133, 23). Beim Verlassen wird zuerst nachgefragt: Das ✕ bei (23, 23) öffnet ein Modal „Close Hairstyle Editor“ mit Save as new item / Overwrite / Close without saving.

Als VRM exportieren — Teilen-Symbol (2464, 23) → Export as VRM → Vollbild-Exportseite mit der blauen Export-Pill bei ≈ (2412, 197) → VRM-Settings-Modal (zentriert, ungefähr x 1000–1560, scrollbar): Export Format-Buttons VRM1.0/VRM0.0, Avatar Name Pflichtfeld, Version, Creators Pflichtfeld, Urheber/Kontakt/Referenzen, Nutzungskontrollkästchen; die Export-Pille bleibt grau und wurde grau undinaktiv, bis beide Pflichtfelder ausgefüllt sind → Wine-Speicherdialog (eigenes Fenster, Titel Export): Das Feld File name: ist beim Öffnen fokussiert und vorausgewählt, sodass eine Windows-Pfadangabe diesen Inhalt ersetzt und die Eingabetaste den vorbelegten Button auslöst. Das Proton-Präfix mappt Z:\ auf /, also wird aus /home/nuri/x Z:\home\nuri\x. **Klicken Sie nicht** auf einen durch OCR gefundenen Save-Button: Die Beschriftung Save in: passt auf dieselbe Suchvorlage.

Was ist fragil

• OCR ist die gesamte Verortungslogik. Kleine, gesperrt geschriebene oder helle Symbole auf dunklem Grund werden geteilt oder übersehen (Export → E + xport). Icons haben überhaupt keinen Text – diese Anker sind fest codierte Fensteranteile und verschieben sich, wenn pixiv die UI umstellt.

• Feste Anker sind anteilige Werte, die bei 2560×1440 und Skalierung 1,25 gemessen wurden. Ein anderer Monitor erfordert eine Neubemessung.

• Modaldialoge erscheinen außerhalb des Suchbereichs und schlucken Klicks lautlos.

• Timeing. Die 3D-Ansicht erscheint ca. 5 s nach Auswahl einer Basis; der Export dauert 5–30 s (bei größeren Modellen länger).

• Der Wine-Dialog ist ein separates Fenster mit eigener Klasse und Geometrie – verwenden Sie dort vroid_screenshot(whole_screen=true).

• Sprache. Diese Suchvorlagen setzen die englische UI voraus. Falls VRoid auf Deutsch? Nein – Englisch? Wenn VRoid Japanisch ist, wastonen Sie in kebab ⋮ → Settings → Language umstellen.

• Der Bildschirmschoner können die Sitzung mitten im Lauf übernehmen. Der Schoner weigert sich, den Text und das zu bedienen... eigentlich: Der Schutzmechanismus verweigert die Eingabe in den Bildschirmschoner und schließt dieses eine Fenster (und nur dieses), bevor er etwas tut.

Sicherheitshinweis

Dieser Server injiziert echte Maus- und Tastaturereignisse in Ihre live-Desktop-Sitzung und erstellt zu davon Screenshots. Das ist der entire Zweck, und es genau das Risiko:

• Screenshots können beliebige Bildschirminhalte erfassen – whole_screen=true zeichnet alles auf, und die Aufnahmen landen unverschlüsselt auf der Festplatte.

• Tastatureingaben gehen an das Element, das den Fokus gerade hält. Der Treiber weigert sich, zu handeln, solange nicht VRoid Studio das aktive Fenster ist, aber ein kompromittierter oder sorgloser Prompt kann trotzdem überall innerhalb von VRoid klicken.

• vroid_launch(restart=true) tötet VRoid Studio und verwirft ungespeicherte Arbeit.

• Hier ist nichts sandboxed, und es gibt keinen Bestätigungsschritt.

Führen Sie es beaufsichtigt – in einer Sitzung, die Sie überwachen auf eine laufende Session und überwachen Sie, undlassen Sie keinen Agenten unbeaufsichtigt daran arbeiten. vroid_release() gibt den Desktop zurück, wenn Sie fertig sind.

Entwicklung

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.driverre.CLI) ist die Shell-Schnittstelle the "implementation" – launch, shot, find, click, tab, slider usw. – handlich zum Debuggev, ohne einen MCP-Client in die Schleife einzubeziehen.

Dankeschön und Lizenz

Der Treiber (src/mcp_vroid/driver/, native/) entstand als der Sprachtest tools/vroid-driver inn meinem eigenen arrakis-Projekt und ist hier zusammen mit dem MCP-Server darum entfernt.

MIT – siehe LICENSE.