AI导哈

VR聊天AI控制桥接器

通过OSC协议实现AI助手与VRChat的交互，支持虚拟角色控制、消息发送和VR事件响应。

  • by Krekun
  • TypeScript
  • 本地部署
  • 31 星标
  • 更新于
在 GitHub 查看 Krekun/vrchat-mcp-osc

使用说明

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 claude_desktop_config.json 文件：

{
  "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桌面

  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 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许可证将此软件用于非商业目的，即表示您同意该许可证的条款。商业用户必须获得上述商业许可证。

致谢

  • OSC集成的VRChat团队
  • 标准化AI接口的模型上下文协议
  • Claude MCP实现的拟人化

相关 MCP