VRChat MCP OSC

VRChat MCP OSC 提供了一个 AI 助手和 VRChat 之间的桥梁，它使用模型上下文协议 (MCP)，从而在虚拟现实环境中实现 AI 驱动的头像控制和互动。

概述

通过利用 OSC (开放声音控制) 与 VRChat 通信，VRChat MCP OSC 允许像 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 配置
{
  "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 服务器实现 (主入口点)
│   ├── 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 实现