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
Claude Desktop（支持 MCP）

与 Claude Desktop 一起使用

克隆和 npm 链接

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

配置 Claude 桌面

通过编辑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 主机	本地主机	对于 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`	启用调试日志记录	错误的	输出详细日志
`--no-relay`	禁用中继服务器	错误的	不使用中继服务器时

可用的 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 聊天框发送消息

故障排除

常见问题

VRChat 不响应命令
- 确保在 VRChat 设置中启用 OSC
- 检查 VRChat 和 MCP 配置之间的 OSC 端口是否匹配
- 重启 VRChat 和 Claude Desktop
MCP 服务器未启动
- 确保安装了 Node.js 18+
- 检查命令行参数是否有错误
- 尝试使用--debug标志运行以获取更详细的日志
- 如果直接参数不起作用，请使用npx vrchat-mcp-osc -- --debug
NPX 执行问题
- 如果参数无法识别，请尝试使用双破折号格式： npx vrchat-mcp-osc -- --debug
- 在 Windows 上，尝试以管理员权限在命令提示符中运行
- 如果您在全局安装时遇到问题，请尝试本地 npm 链接方法

项目结构

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 集成
标准化人工智能接口的模型上下文协议
Anthropic 为 Claude 的 MCP 实现

Integrations