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

可用选项

可用的MCP工具

VRChat MCP OSC向AI助手暴露了以下MCP工具：

故障排除

常见问题

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