VRChat OSC Protocol Bridge

Introduction

This software package facilitates communication between artificial intelligence agents, specifically those supporting the Model Context Protocol (MCP), and the VRChat application. Leveraging the Open Sound Control (OSC) standard, this bridge allows for dynamic, AI-driven manipulation of in-world elements, particularly avatars. This process mirrors how sophisticated, multi-person teams manage complex tasks in commercial game creation, though here the focus is on real-time virtual world interaction.

Key Features

For every retained original relevant section: upgrade its heading to bold form (e.g. '## Setup').

Avatar Control

Manipulation of avatar parameters and visual expressions is readily accessible.

Movement Control

Direct the avatar's positional coordinates and orientation within the virtual space.

Communication

Capability to transmit textual messages directly into the VRChat chat system.

Menu Access

Functions are provided for toggling standard VRChat interface components.

Avatar Information

Retrieve current properties and associated parameters belonging to the active avatar.

Seamless VRChat Integration

The system attempts automatic identification of various avatar configurations for simpler setup.

System Requirements

To successfully utilize this bridging component, certain foundational software prerequisites must be satisfied.

• Node.js version 18 or newer must be installed on the host system.
• VRChat must be running with its internal OSC communication feature explicitly enabled.
• The controlling agent, such as Claude Desktop, requires active MCP support capabilities.

Using with Claude Desktop

Integrating this component with the desktop interface involves several distinct setup steps.

Clone and npm link

To obtain the necessary files and prepare the package for local use, execute these sequential shell commands:

git clone https://github.com/Krekun/vrchat-mcp-osc
cd vrchat-mcp-osc
npm link

Configure Claude Desktop

Configuration requires modification of the claude_desktop_config.json file, specifying the connection details for the bridge server.

{
  "mcpServers": {
    "vrchat-mcp-osc": {
      "command": "npx",
      "args": [
        "vrchat-mcp-osc"
      ]
    }
  }
}

Command Line Options

Customization of the server's operational parameters is possible via command-line flags during execution.

# 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

This table details the various selectable operational arguments and their default settings for the server process.

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

This system exposes several distinct tools that the controlling AI agent can invoke for interaction.

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

This section addresses common operational failures encountered during system usage.

Common Issues

1. VRChat not responding to commands Verify that the OSC setting is active within VRChat’s configuration menus. Confirm port numbers align precisely between VRChat and the MCP bridge configuration. A full restart of both VRChat and the controlling application is often helpful.

2. MCP server not starting Confirm that Node.js version 18 or newer is correctly installed. Scrutinize command-line inputs for any syntactical mistakes. Utilizing the --debug flag can reveal verbose logs that pinpoint the source of the failure. If direct argument passing fails, try specifying them using the double dash format.

3. NPX execution issues If command-line arguments are ignored, consider prefacing the command with two hyphens: npx vrchat-mcp-osc -- --debug. On Windows systems, elevation to administrator privileges might resolve permission-related startup difficulties. If issues persist with global invocations, revert to the local npm link approach previously detailed.

Project Structure

The repository is organized into several distinct packages for modular development.

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

Guidance is provided here for those intending to build the software directly from its source files.

Build From Source

Follow these steps to clone the repository and prepare the development environment for building and testing:

# 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

Related Topics

These concepts relate to the underlying technologies and practices associated with this tool and game development generally.

• Open Sound Control (OSC) implementation in real-time systems.
• The evolution of video game development from single authorship to large production teams.
• Use of proprietary and off-the-shelf game engines in modern production.
• The concept of iterative development, similar to early access models, in software delivery.

Extra Details

This package functions as a specific bridge, analogous to how specialized tools are developed to handle unique technical requirements within larger interactive projects. While commercial game creation involves complex phases like pre-production and quality assurance, this tool focuses solely on the communication layer between an external intelligence and the VRChat client, bypassing manual input for avatar scripting.

Conclusion

This utility effectively automates many interactive functions within VRChat via a structured protocol, moving control from direct user input to AI command structures. This streamlines interaction within virtual worlds, offering a tool that contributes to more dynamic and complex virtual experiences, similar to how larger teams build intricate gameplay systems in modern video game development.