VRChat MCP OSC

VRChat MCP OSC 提供了一个桥梁，通过模型上下文协议（MCP）连接AI助手与VRChat，使AI能够驱动虚拟现实环境中的角色控制和互动。

概述

通过利用OSC（开放声音控制）与VRChat通信，VRChat MCP OSC 允许像Claude这样的AI助手：

• 控制角色参数和表情
• 在VRChat中发送消息
• 响应各种VR事件 以及更多功能——所有这些都通过模型上下文协议提供的高级API实现。

主要特性

• 角色控制：操作角色参数和表情
• 移动控制：直接控制角色的移动和方向
• 通信：通过VRChat聊天框发送消息
• 菜单访问：切换VRChat菜单和界面元素
• 角色信息：查询角色属性和参数
• 无缝集成VRChat：自动检测角色配置

系统要求

• Node.js 18或更高版本
• 启用OSC的VRChat
• 支持MCP的Claude Desktop

使用Claude Desktop

克隆并链接npm

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

配置Claude Desktop

通过编辑claude_desktop_config.json文件来配置Claude Desktop：

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

命令行选项

该服务器支持多种命令行参数以进行定制化设置：

# Claude Desktop配置
{
  "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"             
      ]
    }
  }
}

可用选项

选项	描述	默认值	备注
--websocket-port <端口>	WebSocket端口	8765	用于WebSocket通信
--websocket-host <主机>	WebSocket主机	localhost	用于WebSocket通信
--osc-send-port <端口>	发送OSC端口	9000	发送到VRChat的端口
--osc-send-ip <IP地址>	发送OSC IP地址	127.0.0.1	发送到VRChat的地址
--osc-receive-port <端口>	接收OSC端口	9001	从VRChat接收的端口
--osc-receive-ip <IP地址>	接收OSC IP地址	127.0.0.1	从VRChat接收的地址
--debug	启用调试日志	false	输出详细日志
--no-relay	禁用中继服务器	false	不使用中继服务器时

可用的MCP工具

VRChat MCP OSC向AI助手提供了以下MCP工具：

工具名称	描述
get_avatar_name	获取当前角色的名字
get_avatar_parameters	列出可用的角色参数
set_avatar_parameter	设置特定的角色参数
set_emote_parameter	触发角色表情
move_avatar	移动角色到指定方向
look_direction	控制角色的视线方向
jump	让角色跳跃
menu	切换VRChat菜单
voice	切换语音功能
send_message	向VRChat聊天框发送消息

故障排除

常见问题

1. VRChat未响应命令

   • 确保在VRChat设置中启用了OSC
   • 检查VRChat和MCP配置中的OSC端口是否匹配
   • 重启VRChat和Claude Desktop

2. MCP服务器无法启动

   • 确保已安装Node.js 18+
   • 检查命令行参数是否有误
   • 尝试使用--debug标志运行以获取更详细的日志
   • 如果直接参数不起作用，尝试使用npx vrchat-mcp-osc -- --debug

3. NPX执行问题

   • 如果参数不被识别，尝试使用双破折号格式：npx vrchat-mcp-osc -- --debug
   • 在Windows上，尝试以管理员权限在命令提示符中运行
   • 如果全局安装出现问题，尝试使用本地npm链接方法

项目结构

vrchat-mcp-osc/
├── packages/
│   ├── mcp-server/    # MCP服务器实现（主要入口点）
│   ├── relay-server/  # WebSocket到OSC的中继
│   ├── types/         # 共享TypeScript接口
│   └── utils/         # 常用工具
└── pnpm-workspace.yaml  # 工作区配置

开发

从源代码构建

# 克隆仓库
git clone https://github.com/Krekun/vrchat-mcp-osc
cd vrchat-mcp-osc

# 安装依赖
pnpm install

# 构建所有包
pnpm -r build

# 开发模式
pnpm -r dev

许可证

VRChat MCP OSC采用双重许可方式如下：

对于非商业用途： 您可以在MIT许可证条款下使用、修改和重新分发软件。 （详情参见MIT许可证文件。）

对于商业用途： 商业使用此软件需要单独的商业许可证。

通过在MIT许可证下使用本软件进行非商业用途，您同意该许可证的条款。商业用户必须按照上述描述获得商业许可证。

致谢

• VRChat团队，因OSC集成
• 模型上下文协议，提供标准化的AI接口
• Anthropic，因Claude的MCP实现