VRChat OSC MCP server

This server bridges AI assistants with VRChat using the Model Context Protocol (MCP), allowing AI to control avatars, send messages, and respond to events in VR environments.

Installation

Requirements

• Node.js 18 or higher
• VRChat with OSC enabled
• Claude Desktop (with MCP support)

Setup

1. Clone the repository and create a global link:

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

2. Configure Claude Desktop by editing the claude_desktop_config.json file:

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

Configuration Options

You can customize the server behavior with command-line arguments:

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

Option	Description	Default
--websocket-port <port>	WebSocket port	8765
--websocket-host <host>	WebSocket host	localhost
--osc-send-port <port>	OSC send port	9000
--osc-send-ip <ip>	OSC send IP	127.0.0.1
--osc-receive-port <port>	OSC receive port	9001
--osc-receive-ip <ip>	OSC receive IP	127.0.0.1
--debug	Enable debug logging	false
--no-relay	Disable relay server	false

Usage

Once configured, the MCP server exposes these tools to AI assistants:

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

VRChat Not Responding to Commands

• Ensure OSC is enabled in VRChat settings
• Verify that OSC ports match between VRChat and MCP configuration
• Restart VRChat and Claude Desktop

MCP Server Not Starting

• Confirm 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

NPX Execution Issues

• If arguments aren't being recognized, try: npx vrchat-mcp-osc -- --debug
• On Windows, try running in a command prompt with administrator privileges
• If global installation causes problems, use the local npm link approach

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "vrchat-mcp-osc" '{"command":"npx","args":["vrchat-mcp-osc"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect