JinDaGe - VRChat OSC MCP Details

article

README

🚀 VRChat MCP OSC 中文版

VRChat MCP OSC 通过 Model Context Protocol (MCP) 在 AI 助手与 VRChat 之间搭建桥梁，实现基于人工智能的头像控制以及虚拟现实环境中的交互，为用户带来全新的沉浸式体验。

🚀 快速开始

VRChat MCP OSC 借助 OSC（开放声音控制）与 VRChat 进行通信。它允许像 Claude 这类 AI 助手，通过 MCP 提供的高级别 API，实现以下功能：

控制头像参数和表情
发送消息到 VRChat 聊天框
响应各种 VR 事件
以及其他更多功能

✨ 主要特性

头像控制：可灵活调节头像参数与表情，让头像生动展现各种神态。
运动控制：精准指挥头像移动和方向，实现自然的虚拟行动。
通信功能：轻松发送消息至 VRChat 聊天框，实现信息交互。
菜单访问：便捷切换 VRChat 菜单及界面元素，提升操作效率。
头像信息：随时查询头像属性和参数，深入了解头像状态。
无缝集成：自动检测头像配置，无需手动繁琐设置。

📦 安装指南

系统需求

Node.js：需要安装 Node.js v16.0 或以上版本。
VRChat：需要启用 OSC 支持的 VRChat 版本。
Claude：必须使用支持 MCP 接口的 Claude 版本。

安装步骤

# 克隆仓库
git clone https://github.com/Krekun/vrchat-mcp-osc
cd vrchat-mcp-osc

# 创建 npm 链接
npm link packages/mcp-server
npm link packages/relay-server

修改配置文件

复制 config.json 到项目根目录，并根据需求调整以下参数：

{
  "mcpPort": 12345,
  "wsPort": 12346,
  "debugMode": true
}

💻 使用示例

命令行选项

参数说明

--mcp-port：MCP 服务器监听端口，缺省值为 12345。
--ws-port：WebSocket 相关服务端口，默认是 12346。
--debug：启用调试模式，提供详细日志输出。

示例

启动 MCP 服务器并指定自定义端口：

node index.js --mcp-port 12345 --ws-port 12346

可用工具

以下是 AI 助手可用的 MCP 工具及其描述： | 工具名称 | 描述 | | -------------- | ------------------ | | HeadPoseTool | 调节头像姿态角度 | | ExpressionTool | 控制面部表情强度 | | AvatarTool | 切换头像模型和材质 |

📚 详细文档

故障排除

常见问题

无法连接到 VRChat：检查 OSC 支持是否开启，确认目标地址和端口正确。
MCP 服务未响应：确保 Node.js 版本符合要求，并且所有依赖已安装。

项目结构

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 许可证使用本软件，您需遵守该许可条款。商业用户必须获取相应的商业许可。

致谢

感谢以下团队与协议：

VRChat 团队为 OSC 集成
Model Context Protocol 提供标准化 AI 接口
Anthropic 实现 Claude 的 MCP 技术

VRChat OSC