VRChat MCP OSC

# VRChat MCP OSC **VRChat MCP OSC** provides a bridge between AI assistants and VRChat using the Model Context Protocol (MCP), enabling AI-driven avatar control and interactions in virtual reality environments. ## Overview By leveraging OSC (Open Sound Control) to communicate with VRChat, **VRChat MCP OSC** allows AI assistants such as Claude to: - Control avatar parameters and expressions - Send messages in VRChat - Respond to various VR events And more—all through the high-level API provided by the Model Context Protocol. ## Key Features - **Avatar Control**: Manipulate avatar parameters and expressions - **Movement Control**: Direct avatar movement and orientation - **Communication**: Send messages through VRChat's chatbox - **Menu Access**: Toggle VRChat menu and interface elements - **Avatar Information**: Query avatar properties and parameters - **Seamless VRChat Integration**: Automatic detection of avatar configurations ## System Requirements - Node.js 18 or higher - VRChat with OSC enabled - Claude Desktop (with MCP support) ## Using with Claude Desktop ### Clone and npm link ```bash git clone https://github.com/Krekun/vrchat-mcp-osc cd vrchat-mcp-osc npm link ``` ### Configure Claude Desktop Configure Claude Desktop by editing the `claude_desktop_config.json` file: ```json { "mcpServers": { "vrchat-mcp-osc": { "command": "npx", "args": [ "vrchat-mcp-osc" ] } } } ``` ### Command Line Options The server supports various command-line arguments for customization: ```bash # Claude Desktop configuration { "mcpServers": { "vrchat-mcp-osc": { "command": "npx", "args": [ "vrchat-mcp-osc", "--websocket-port", "8765", "--websocket-host", "localhost", "--osc-send-port", "9000", "--osc-send-ip", "127.0.0.1", "--osc-receive-port", "9001", "--osc-receive-ip", "127.0.0.1", "--debug" ] } } } ``` ### Available Options | Option | Description | Default | Notes | |--------|-------------|---------|-------| | `--websocket-port <port>` | WebSocket port | 8765 | For WebSocket communication | | `--websocket-host <host>` | WebSocket host | localhost | For WebSocket communication | | `--osc-send-port <port>` | OSC send port | 9000 | Port for sending to VRChat | | `--osc-send-ip <ip>` | OSC send IP | 127.0.0.1 | Address for sending to VRChat | | `--osc-receive-port <port>` | OSC receive port | 9001 | Port for receiving from VRChat | | `--osc-receive-ip <ip>` | OSC receive IP | 127.0.0.1 | Address for receiving from VRChat | | `--debug` | Enable debug logging | false | Output detailed logs | | `--no-relay` | Disable relay server | false | When not using relay server | ## Available MCP Tools VRChat MCP OSC exposes the following MCP tools to AI assistants: | Tool Name | Description | |-----------|-------------| | `get_avatar_name` | Retrieves the current avatar's name | | `get_avatar_parameters` | Lists available avatar parameters | | `set_avatar_parameter` | Sets a specific avatar parameter | | `set_emote_parameter` | Triggers avatar emotes | | `move_avatar` | Moves the avatar in a specific direction | | `look_direction` | Controls avatar's view direction | | `jump` | Makes the avatar jump | | `menu` | Toggles the VRChat menu | | `voice` | Toggles voice features | | `send_message` | Sends a message to the VRChat chatbox | ## Troubleshooting ### Common Issues 1. **VRChat not responding to commands** - Ensure OSC is enabled in VRChat settings - Check that the OSC ports match between VRChat and MCP configuration - Restart VRChat and Claude Desktop 2. **MCP server not starting** - Ensure Node.js 18+ is installed - Check command line arguments for errors - Try running with `--debug` flag for more detailed logs - Use `npx vrchat-mcp-osc -- --debug` if direct arguments don't work 3. **NPX execution issues** - If arguments aren't being recognized, try using the double dash format: `npx vrchat-mcp-osc -- --debug` - On Windows, try running in a command prompt with administrator privileges - If you're having trouble with global installation, try the local npm link approach ## Project Structure ``` vrchat-mcp-osc/ ├── packages/ │ ├── mcp-server/ # MCP server implementation (main entry point) │ ├── relay-server/ # WebSocket to OSC relay │ ├── types/ # Shared TypeScript interfaces │ └── utils/ # Common utilities └── pnpm-workspace.yaml # Workspace configuration ``` ## Development ### Build From Source ```bash # Clone the repository git clone https://github.com/Krekun/vrchat-mcp-osc cd vrchat-mcp-osc # Install dependencies pnpm install # Build all packages pnpm -r build # Development mode pnpm -r dev ``` ## License VRChat MCP OSC is dual-licensed as follows: For Non-Commercial Use: You may use, modify, and redistribute the software under the terms of the MIT License. (See the MIT License file for details.) For Commercial Use: Commercial use of this software requires a separate commercial license. By using this software under the MIT License for non-commercial purposes, you agree to the terms of that license. Commercial users must obtain a commercial license as described above. ## Acknowledgments - VRChat team for the OSC integration - Model Context Protocol for the standardized AI interface - Anthropic for Claude's MCP implementation