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