VRChat MCP OSC

Bridges AI assistants with VRChat via MCP over OSC to control avatars, move, chat, and react to events.

typescript

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "krekun-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"
      ]
    }
  }
}

VRChat MCP OSC is a bridge that lets you control VRChat avatars and interactions through AI assistants using the Model Context Protocol over OSC. It enables high-level avatar control, messaging, and event responses by connecting your MCP-enabled client to VRChat’s OSC interface.

How to use

You connect an MCP client to VRChat through the OSC bridge and then issue commands to control avatar parameters, trigger emotes, move and orient the avatar, send messages, and toggle menus. Use the available MCP tools to perform actions like setting avatar parameters, moving the avatar, or sending chat messages. The bridge automatically discovers avatar configurations and exposes a consistent API for AI assistants to interact with VRChat.

How to install

Prerequisites you need before installing: Node.js 18 or higher, VRChat with OSC enabled, and an MCP-enabled client such as Claude Desktop.

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

# Install dependencies and link for development
npm link

Additional steps you will take to run the server

Configure your MCP client to connect to VRChat MCP OSC by using the provided runtime command and optional flags to tailor the connection, ports, and debugging behavior.

{
  "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"
      ]
    }
  }
}

Troubleshooting

If VRChat does not respond to commands, verify that OSC is enabled in VRChat, ensure the OSC ports match between VRChat and the MCP configuration, and restart both VRChat and your MCP client. If the MCP server fails to start, confirm Node.js 18+ is installed and run with the debug flag to capture more details. For NPX execution issues, try using the double-dash format and run with administrator privileges on Windows if needed.

Development

If you are developing locally, you can build and run the project in development mode after installing dependencies. Use a workspace tool to install and build all packages, then start in development mode.

# 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

Available tools

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.

voice

Toggles voice features.

send_message

Sends a message to the VRChat chatbox.

Built by

VeilStrat

AI signals for GTM teams