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

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:

{
  "mcpServers": {
    "vrchat-mcp-osc": {
      "command": "npx",
      "args": [
        "vrchat-mcp-osc"
      ]
    }
  }
}

Command Line Options

The server supports various command-line arguments for customization:

# 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

# 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