VRChat MCP OSC Integration

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

Available MCP Tools

VRChat MCP OSC exposes the following MCP tools to AI assistants:

Troubleshooting

Common Issues

1. VRChat not responding to commands
2. Ensure OSC is enabled in VRChat settings
3. Check that the OSC ports match between VRChat and MCP configuration

4. Restart VRChat and Claude Desktop

5. MCP server not starting

6. Ensure Node.js 18+ is installed
7. Check command line arguments for errors
8. Try running with --debug flag for more detailed logs

9. Use npx vrchat-mcp-osc -- --debug if direct arguments don't work

10. NPX execution issues

11. If arguments aren't being recognized, try using the double dash format: npx vrchat-mcp-osc -- --debug
12. On Windows, try running in a command prompt with administrator privileges
13. 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