{"id":"e3e527b5-6969-4bae-92e0-cd16df1bb0dd","slug":"warudo-mcp","kind":"mcp","name":"warudo-mcp","summary":"Model Context Protocol (MCP) server & runtime bridge for Warudo 3D virtual production. Available on npm: warudo-mcp-server","owner":"KhoaDayy","repoUrl":"https://github.com/KhoaDayy/warudo-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-24T16:18:52.000Z","addedAt":"2026-10-21T18:09:05.928Z","logoUrl":"https://avatars.githubusercontent.com/u/72400535?u=0b457ed8924e92dc4c66c289c9dcb1144d93c4aa&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","developer-tools","design-media"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T17:58:42.219Z","sample":false,"url":"https://conduits.dev/tools/warudo-mcp","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Warudo MCP\n\n[![CI](https://github.com/KhoaDayy/warudo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/KhoaDayy/warudo-mcp/actions/workflows/ci.yml)\n[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Protocol Version](https://img.shields.io/badge/Bridge%20Protocol-v2-blue.svg)](docs/MIGRATION.md)\n[![NPM Version](https://img.shields.io/npm/v/warudo-mcp-server.svg?logo=npm)](https://www.npmjs.com/package/warudo-mcp-server)\n[![Steam Workshop](https://img.shields.io/badge/Steam%20Workshop-MCP%20Bridge-1b2838.svg?logo=steam)](https://steamcommunity.com/sharedfiles/filedetails/?id=3809919307)\n\n[English](README.md) · [Tiếng Việt](README.vi.md)\n\nA Model Context Protocol (MCP) server providing standard, model-agnostic control over [Warudo](https://warudo.app/) 3D virtual production and VTubing scenes via stdio.\n\n<p align=\"center\">\n  <img src=\"docs/mcp_bridge_workshop.jpg\" alt=\"Warudo MCP Bridge Banner\" width=\"480\">\n</p>\n\n---\n\n## Overview\n\nControlling 3D virtual production software from Large Language Models usually requires proprietary scripts or brittle, model-specific bindings. \n\n**Warudo MCP** exposes Warudo's native capabilities directly to AI assistants (Claude Desktop, Cursor, Cline, Roo Code, Windsurf) through 26 strongly-typed MCP tools. The bridge operates purely on generic primitives—controlling cameras, lighting, avatar transforms, material properties, and blueprint node networks—without coupling to specific avatars or proprietary tracking setups.\n\n### Transport Architecture\n\n```text\nMCP Host (Claude / Cursor / Cline)\n       │ (JSON-RPC 2.0 over stdio)\n       ▼\nTypeScript MCP Server (warudo-mcp-server)\n       ├── Native WebSocket API (ws://[::1]:19053) ──► Data ports, Blueprint graphs, Flow execution\n       └── Bridge Plugin (ws://localhost:5678)     ──► Scene inventory, Hierarchy query, Material overrides\n```\n\n* **Native Control Plane (`:19053`)**: Interacts directly with Warudo Core for entity data ports, triggers, and full blueprint graph manipulation.\n* **Bridge Plugin (`:5678`)**: A compiled, auto-starting Unity mod (`[PluginType]`) that provides deep scene inventory traversal and transient Material PropertyBlock overrides without using prohibited `System.Reflection` APIs.\n\n---\n\n## Features\n\n* **Complete Scene Discovery**: Inspect all active assets, character entities, directional lights, and plugins with paginated type catalogs (`warudo_scene_inventory`, `warudo_list_assets`).\n* **Autonomous Camera & Staging**: Adjust orbit offsets, rotation, field of view, and trigger screenshots dynamically.\n* **Transform Protection**: Built-in serialization guard automatically double-stringifies nested `TransformData` properties (`Position`, `Rotation`, `Scale`) to prevent native deserializer corruption and late-update crash loops.\n* **Blueprint Node Graph Editing**: Create, delete, rename, and enable blueprints; add and wire node pins; and invoke flow execution paths programmatically (`warudo_manage_graph`, `warudo_manage_node`, `warudo_manage_connection`, `warudo_invoke_flow`).\n* **Transient Material Overrides**: Modify shader properties and material keywords at runtime using non-destructive MaterialPropertyBlocks that reset cleanly when scenes unload.\n* **Explicit Execution Semantics**: Mutations that fail validation return `NOT_EXECUTED`. Unacknowledged network timeouts return `UNKNOWN` and retire the underlying socket before retrying.\n\n---\n\n## Requirements\n\n* **Operating System**: Windows 10/11 (required by Warudo)\n* **Node.js**: `v22.0.0` or higher\n* **Warudo**: Version `0.15.0` or higher installed\n\n---\n\n## Quick Start (Zero Git Clone Required)\n\n### 1. Install Warudo Plugin\nSubscribe to the official mod on Steam Workshop (no Unity compilation required):\n👉 [**MCP Bridge on Steam Workshop**](https://steamcommunity.com/sharedfiles/filedetails/?id=3809919307)\n\n*Alternatively, compile `warudo-plugin/` with Warudo Mod Tools and place `Warudo-MCP.warudo` into `%APPDATA%\\..\\LocalLow\\HakuyaLabs\\Warudo\\Plugins\\`.*\n\n### 2. Configure Your AI Client\n\n#### Option A: One-Line PowerShell Installer\nOpen PowerShell and run:\n```powershell\nirm https://raw.githubusercontent.com/KhoaDayy/warudo-mcp/main/install.ps1 | iex\n```\n*Verifies Node.js, purges legacy Playground scripts, and configures Claude Desktop, Cursor, Cline, Roo Code, and Windsurf automatically.*\n\n#### Option B: AI Agent Self-Setup Prompt\nCopy and paste this prompt directly into your AI chat (Cursor, Claude, or Cline):\n```text\nPlease connect to my Warudo instance via MCP:\n1. Register the \"warudo\" MCP server in your config using command \"npx\" with args [\"-y\", \"warudo-mcp-server\"].\n2. Remind me to subscribe to the \"MCP Bridge\" plugin on Steam Workshop (https://steamcommunity.com/sharedfiles/filedetails/?id=3809919307) if I haven't already.\n3. Once Warudo is running with a scene open, call warudo_status to verify our live connection.\n```\n\n#### Option C: Manual Client Configuration\nAdd the server entry to your MCP client configuration file:\n\n**Claude Desktop** (`%APPDATA%\\Claude\\claude_desktop_config.json`) or **Cursor** (`~/.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"warudo\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"warudo-mcp-server\"]\n    }\n  }\n}\n```\n\n---\n\n## Tool Surface\n\nThe server exposes 26 strongly-typed tools categorized into 7 functional domains:\n\n| Domain | Tools | Description |\n|---|---|---|\n| **Health** | `warudo_status`, `warudo_frame_state` | Inspect host PID, active scene, FPS, and frame counter. |\n| **Scene Discovery** | `warudo_scene_inventory`, `warudo_list_assets`, `warudo_get_selected_asset`, `warudo_get_plugins`, `warudo_get_asset_types`, `warudo_get_node_types` | Enumerate scene objects, plugins, asset types, and blueprint node catalogs. |\n| **Entity** | `warudo_inspect_entity`, `warudo_get_entity_port_value`, `warudo_set_entity_port_value`, `warudo_invoke_entity_trigger`, `warudo_send_plugin_message` | Read/write data ports, fire trigger buttons, and dispatch plugin messages. |\n| **Blueprints** | `warudo_get_selected_graph`, `warudo_list_blueprints`, `warudo_import_graph`, `warudo_export_graph`, `warudo_set_node_data_input` | List and serialize blueprint graphs; import with `dryRun` validation. |\n| **Graph Editing** | `warudo_manage_graph`, `warudo_manage_node`, `warudo_manage_connection`, `warudo_invoke_flow` | Create/remove/rename graphs, manage nodes, wire pins, and trigger flow inputs. |\n| **Unity Runtime** | `warudo_list_hierarchy`, `warudo_set_gameobject_active`, `warudo_set_material_property` | Traverse GameObject hierarchy, toggle objects, and apply material properties. |\n| **Compatibility** | `warudo_api` | Raw passthrough for native Warudo actions not covered by typed tools. |\n\n### Value Formatting & Validation\n\nPort setters support explicit typed prefixes:\n* Primitives: `float:0.5`, `int:42`, `bool:true`, `string:hello`\n* Vectors: `vector3:0,1.5,-2`\n* Colors: `color:#ff00ffff` or `color:1,0,1,1` (uniform 0–1 or 0–255 scale)\n* JSON / Structured: `json:{\"value\": 2}`\n\n---\n\n## Configuration\n\n| Environment Variable | Default Value | Description |\n|---|---|---|\n| `WARUDO_API_WS_URL` | `ws://[::1]:19053/` | Full WebSocket URL for Warudo Native API (overrides host/port). |\n| `WARUDO_API_WS_HOST` / `WARUDO_API_WS_PORT` | `::1` / `19053` | Host and port for Warudo Native API. |\n| `WARUDO_WS_URL` | `ws://localhost:5678/` | Full WebSocket URL for compiled C# MCP Bridge plugin. |\n| `WARUDO_WS_HOST` / `WARUDO_WS_PORT` | `localhost` / `5678` | Host and port for C# MCP Bridge plugin. |\n| `WARUDO_API_TOKEN` | *(Auto-discovered)* | 32-character hexadecimal auth token. Discovered automatically from `Player.log`. |\n\n---\n\n## Project Structure\n\n```txt\nwarudo-mcp/\n├── .github/workflows/ci.yml       # Multi-platform CI (Ubuntu & Windows)\n├── docs/\n│   ├── MIGRATION.md               # Upgrading from v0.1/v0.2 to v0.3 protocol v2\n│   └── VERIFICATION.md            # Automated testing & live acceptance matrix\n├── install.ps1                    # One-line automated PowerShell installer\n├── mcp-server/                    # TypeScript MCP Server package\n│   ├── src/\n│   │   ├── tools/                 # Modular tool schemas (entities, graphs, runtime)\n│   │   ├── server.ts              # MCP server factory with dependency injection\n│   │   ├── values.ts              # Value validation & TransformData safety wrapper\n│   │   ├── warudoApi.ts           # Native WebSocket client (:19053)\n│   │   └── warudoBridge.ts        # Protocol v2 Bridge client (:5678)\n│   └── tests/                     # Automated test suite (37 tests)\n└── warudo-plugin/                 # C# Unity Plugin sources (UMod / .NET Framework)\n    ├── McpBridgePlugin.cs         # Auto-starting [PluginType] lifecycle\n    ├── McpBridgeService.cs        # WebSocketSharp RPC service\n    ├── GameObjectPathResolver.cs  # Reflection-free hierarchy resolver\n    └── MaterialKeywordOverrideStore.cs # Transient material PropertyBlock manager\n```\n\n---\n\n## Development\n\nClone the repository and install dependencies:\n\n```powershell\ngit clone https://github.com/KhoaDayy/warudo-mcp.git\ncd warudo-mcp/mcp-server\nnpm ci\nnpm run build\n```\n\n### Local Commands\n\n```powershell\nnpm run dev             # Run development server with tsx\nnpm run typecheck       # Verify TypeScript types without emitting\nnpm test                # Execute Node.js automated test runner (37 tests)\nnpm run check           # Run typecheck, tests, and npm pack allowlist verification\n```\n\n### Plugin Verification\n\nTo compile the C# plugin sources against your local Warudo installation:\n\n```powershell\npowershell -NoProfile -File scripts/check-bridge.ps1\n```\n\n---\n\n## Documentation\n\n* [Migration Guide](docs/MIGRATION.md): Breaking changes from earlier versions and node retirement records.\n* [Verification Record](docs/VERIFICATION.md): Test harness details, limits, response budgets, and live acceptance checklist.\n* [Refactor Plan](REFACTOR_PLAN.md): Architectural decisions and scope audit history.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n### Acknowledgements\n\n* [Warudo](https://warudo.app/) by Hakuya Labs.\n* [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic.\n* Upstream architectural insights from `StudioRaming/warudo-agent-bridge` and `esprite-VTOKU/WarudoMCP`.\n"}