vrchat-mcp-osc

VRChat MCP OSC

VRChat MCP OSC 使用模型上下文协议（MCP）在 AI 助手与 VRChat 之间搭建桥梁，让 AI 能够在虚拟现实环境中控制化身并进行互动。

概述

VRChat MCP OSC 利用 OSC（开放声音控制）与 VRChat 通信，让 Claude 等 AI 助手能够：

• 控制化身参数和表情
• 在 VRChat 中发送消息
• 响应各种 VR 事件
  以及更多功能——所有操作均通过模型上下文协议提供的高级 API 完成。

主要功能

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

系统要求

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

与 Claude Desktop 配合使用

克隆并执行 npm link

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

可用选项

选项	说明	默认值	备注
--websocket-port <port>	WebSocket 端口	8765	用于 WebSocket 通信
--websocket-host <host>	WebSocket 主机	localhost	用于 WebSocket 通信
--osc-send-port <port>	OSC 发送端口	9000	向 VRChat 发送数据的端口
--osc-send-ip <ip>	OSC 发送 IP	127.0.0.1	向 VRChat 发送数据的地址
--osc-receive-port <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 link 方式

项目结构

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

开发

从源代码构建

# 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

许可证

VRChat MCP OSC 采用以下双重许可：

非商业用途： 你可以根据 MIT 许可证的条款使用、修改和重新分发本软件。 （详情请参阅 MIT 许可证文件。）

商业用途： 商业使用本软件需要单独获取商业许可证。

将本软件用于非商业用途并遵循 MIT 许可证，即表示你同意该许可证的条款。商业用户必须按照上述说明获取商业许可证。

致谢

• 感谢 VRChat 团队提供 OSC 集成
• 感谢 Model Context Protocol 提供标准化的 AI 接口
• 感谢 Anthropic 提供 Claude 的 MCP 实现