mcp-vroid

VRoid Studio의 GUI를 구동하는 MCP 서버입니다. 모든 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  ◄───────────────┘

서버의 엔진은 제 arrakis 프로젝트의 tools/vroid-driver 스파이크를 이 프로젝트에 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는 zwlr_virtual_pointer_unstable_v1용 약 150줄 짜리 C 클라이언트를 컴파일합니다(프로토콜 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

표준 표준 mcpServers JSON:

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

클라이언트는 종종 정화된 환경으로 서버를 실행합니다. 이 서버는 시작 시(src/mcp_vroid/session_env.py)에서 XDG_RUNTIME_DIR, WAYLAND_DISPLAY, HYPRLAND_INSTANCE_SIGNATURE, DISPLAY를 런타임 디렉터리에서 복구하므로 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픽셀만 검사해서 클릭이 6번 실패했습니다.

• 3D 뷰포트의 변화로 판단하지 마세요. VRoid는 모든 프레임을 디더링하므로, 아무것도 없어도 전체 창 diff는 0.98로 읽힙니다. UI 형태를 관찰하세요.

• 슬라이더 드래그보다 숫자 상자를 우선하세요. vroid_set_slider는 정확한 값을 입력하고, 드래그는 숫자 상자가 없는 제어에 사용됩니다.

• 기본 버튼은 색상으로 찾습니다. 파란색 예상 위치의 회색 약이 보이면 앱이 필수 필드가 비어 있다고 알리는 것입니다.

• 전체 2560×1440 프레임의 OCR은 약 10초가 걸립니다. 반드시 region을 전달하세요.

좌표 공간

소스 머신에서는 세 가지 공간이 활성화되어 있고 서로 다릅니다:

도구는 기본적으로 이미지 픽셀(space="image")을 받고 변환하므로, vroid_find_text 결과를 바로 vroid_click에 전달하세요. MCP_VROID_MAX_IMAGE_PX로 이미지가 다운스케일 된 경우 이미지에서 직접 좌표를 읽어 사용하려면 보고된 downscale 배율의 역수를 먼저 곱하거나, vroid_find_text가 항상 원본 픽셀을 반환하므로 그냥 사용하세요.

UI 맵 (VRoid Studio 2.14.0, 영문)

전체 화면 창 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) 캡션이 있습니다 — 캡션 위의 ~100px 지점에 있는 썸네일을 클릭하세요.

편집기 — 탭 줄은 y ≈ 23에 있습니다: Face 97 · Hairstyle 198 · Body 302 · Outfit 392 · Accessories 509 · Look 622. 햄버거 메뉴 ☰ (29, 23) → Save (Ctrl+S), Save As… (Ctrl+Shift+S), import/bulk export, undo/redo, 모델 선택 화면으로 돌아가기 — Escape는 이 메뉴가 닫히지 않으므로, 다른 곳을 클릭하세요. 오른쪽 상단 툴바: 카메라 (2415, 23), 공유/export (2464, 23), 케밥 메뉴 ⋮ (2512, 23). 왼쪽의 아이콘 레일(x ≈ 24, 첫 번째 아이콘 y ≈ 77, 이후 ~48px 간격) = 현재 탭의 하위입니다. 왼쪽 패널 = 프리셋 그리드에 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 모달이 미리 열립니다ol "하려면 Save as new item / Overwrite / Close without saving.

VRM으로 내보내기 — 공유 아이콘 (2464, 23) → Export as VRM → 전체 화면으로 전환됩니다 내보내기 페이지에 파란색 Export 알약이 ≈ (2412, 197)에 있습니다 → VRM Settings 모달(중앙 정렬, ~x 1000~1560, 스크롤 가능): Export Format 라디오 VRM1.0 / VRM0.0, Avatar Name 필수, Version, Creators 필수, 저작권/연락처/참조/사용 관련 체크박스가 있습니다. 내보내기 알약은 두 필수 필드가 모두 채워질 때까지 잿빛으로 비활성 상태를 유지합니다 → Wine 저장 대화 상자 (별도 창이며 제목 Export): File name: 필드가 포커스되고 선택된 상태에서 열리므로 Windows 경로를 입력하면 그 필드가 교체되고 Return 키가 기본선택을 누릅니다. Proton prefix가 Z:\를 /에 매핑하므로, /home/nuri/x는 Z:\home\nuri\x가 됩니다. OCR을 사용해 찾아낸 Save라는 메시지는 클릭하지 않으세요. Save in:레이블이 동일한 needle에 매칭될 수 있습니다.

Brittle한 것들

• OCR이 위치를 파악하는 유일한 요소입니다. 작거나, 간격이 넓거나, 어두운 배경의 레이블은 분리되거나 버려질 수 있습니다(Export → E+xport). 아이콘은 텍스트가 전혀 없습니다 — 그 닻들은 창의 크기에 하드코딩된 비율이며, pixiv가 UI를 플로시키면 이동합니다.

• 고정 앵커는 2560×1440에서 배율 1.25 기준으로 보정된 분수입니다. 다른 것 모니터는 다시 측정해야 할 수도 있습니다.

• 모달은 서치 영역에 나타나지 않고 클릭을 조용히 삼킵니다.

• 타이밍. 3D 뷰포트는 베이스가 선택된 후 ~5초 후에 나타납니다. export는 5~30초 소요됩니다(무거운 모델은 더 오래 걸립니다).

• Wine 대화 상자는 별도의 창이며 자체 클래스와 렌더링 영역이 있습니다. 그 안에서는 vroid_screenshot(whole_screen=true)를 사용하세요.

• Language. 이 기준은 영어 UI를 가정합니다. VRoid가" 창가 메뉴 ⋮ → Settings → Language에서 전환하세요.

• 대기 화면 보호기가 실행 중 세션을 가져갈 수 있습니다. The guard is 화면 보호기에 입력을 거부하고, 작업 전에 해당 창 하나(그 창만)를 닫습니다.

보안 참고

이 서버는 실제 마우스와 키보드 이벤트를 현재 데스크톱 세션에 주입하고 화면을 캡처합니다. 그것이 이 서버의 존재 이유이며, 위험이기도 합니다:

• 스크린샷에는 화면에 입력되는 모든 정보가 포함될 수 있고, whole_screen=true를 사용하면 모든 것이 캡처되며, 캡처 파일은 암호화되지 않은 디스크에 저장됩니다.

• 키 입력은 포커스를 가진 대상으로 전달됩니다. VRoid Studio가 포커스된 창일 때만 실행되지만, 손상되었거나 부주의한 프롬프트는 여전히 VRoid 내부의 아무 위치에서도 클릭할 수 있습니다.

• vroid_launch(restart=true)는 VRoid Studio를 죽이고 저장되지 않은 작업을 잃습니다.

• 여기에는 어떤 것도 샌드박스가 없으며 확인 단계도 없습니다.

보는 사람이 있는 곳에서 실행하세요. 자신이 보고 있는 세션에서만 실행하고, 에이전트가 감독 없이 운전하지 않도록 하십시오. vroid_release()를 호출하면 완료 후 데스크톱을 반환합니다.

Development

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)는 스파이크의 셸( shell ) 인터페이스입니다 — launch, shot, find, click, tab, slider, export, cam, apply-params, … — MCP 클라이언트 없이 디버깅에 편리합니다.

Credits and licence

드라이버(src/mcp_vroid/driver/, native/)는 원래 제 arrakis 프로젝트의 tools/vroid-driver 스파이크에서 시작되었으며, 여기에는 MCP 서버가 그 주위에 감싸인 채 포함되어 있습니다.

MIT — LICENSE 참조.