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

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
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
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