What is Vrchat Mcp Osc

VRChat MCP OSC is a bridge that connects AI assistants with VRChat using the Model Context Protocol (MCP), enabling AI-driven control and interactions of avatars in virtual reality environments.

Use cases

Use cases include controlling avatars in VRChat for gaming, enhancing social interactions in virtual environments, automating responses to VR events, and integrating AI assistants for a more immersive experience.

How to use

To use VRChat MCP OSC, clone the repository and link it using npm. Configure Claude Desktop by editing the configuration file to include the MCP server settings, and customize command-line options for specific functionalities.

Key features

Key features include avatar control for parameters and expressions, movement control, communication through VRChat’s chatbox, menu access, querying avatar properties, and seamless integration with VRChat.

Where to use

VRChat MCP OSC can be used in virtual reality applications, particularly in environments where AI-driven interactions and avatar control are beneficial, such as gaming, social VR, and virtual events.

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

Available MCP Tools

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

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