🚀 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 技术