Vrchat OSC

🚀 VRChat MCP OSC

VRChat MCP OSC bridges the gap between AI assistants and VRChat through the Model Context Protocol (MCP), enabling AI - based avatar control and interaction in virtual reality environments.

🚀 Quick Start

Overview

Using OSC (Open Sound Control) to communicate with VRChat, VRChat MCP OSC allows AI assistants like Claude to:

• Control avatar parameters and expressions.
• Send messages to the VRChat chat box.
• Respond to various VR events. And many more - all made possible by the high - level API provided by MCP.

✨ Features

• Avatar Control: Adjust avatar parameters and expressions.
• Motion Control: Direct avatar movement and orientation.
• Communication: Send messages to the VRChat chat box.
• Menu Access: Switch between VRChat menus and interface elements.
• Avatar Information: Query avatar attributes and parameters.
• Seamless Integration: Automatically detect avatar configurations.

📦 Installation

System Requirements

• Node.js: Node.js v16.0 or higher is required.
• VRChat: A VRChat version with OSC support enabled is needed.
• Claude: A Claude version that supports the MCP interface must be used.

Installation Guide

# Clone the repository
git clone https://github.com/Krekun/vrchat-mcp-osc
cd vrchat-mcp-osc

# Create npm links
npm link packages/mcp-server
npm link packages/relay-server

Configuration File Modification

Copy config.json to the project root directory and adjust the following parameters as needed:

{
  "mcpPort": 12345,
  "wsPort": 12346,
  "debugMode": true
}

📚 Documentation

Command - Line Options

Parameter Description

• --mcp - port: The port on which the MCP server listens. The default value is 12345.
• --ws - port: The port for WebSocket - related services. The default is 12346.
• --debug: Enable debug mode to provide detailed log output.

Example

Start the MCP server and specify custom ports:

node index.js --mcp-port 12345 --ws-port 12346

Available Tools

The following are the MCP tools available to AI assistants and their descriptions:

Troubleshooting

Common Issues

• Unable to connect to VRChat: Check if OSC support is enabled and confirm that the target address and port are correct.
• MCP service not responding: Ensure that the Node.js version meets the requirements and that all dependencies are installed.

Project Structure

vrchat-mcp-osc/
├── packages/
│   ├── mcp-server/    # MCP server implementation (main entry)
│   ├── relay-server/  # WebSocket to OSC relay
│   ├── types/         # Shared TypeScript interfaces
│   └── utils/         # Common utility functions
└── pnpm-workspace.yaml  # Workspace configuration

Development Guide

Source Code Building

# 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

# Run in development mode
pnpm -r dev

📄 License

VRChat MCP OSC uses a dual - license model:

• Non - commercial use: Use, modify, and distribute the software under the MIT license.
• Commercial use: A separate commercial license is required for commercial use. By using this software under the MIT license for non - commercial use, you must comply with the terms of that license. Commercial users must obtain the appropriate commercial license.

Acknowledgments

Thanks to the following teams and protocols:

• The VRChat team for OSC integration.
• The Model Context Protocol for providing a standardized AI interface.
• Anthropic for implementing the MCP technology in Claude.