Skip to main content
Glama

VRChat MCP OSC

VRChat MCP OSC使用模型上下文协议 (MCP) 在 AI 助手和 VRChat 之间架起了一座桥梁,实现了虚拟现实环境中 AI 驱动的化身控制和交互。

概述

通过利用 OSC(开放声音控制)与 VRChat 进行通信, VRChat MCP OSC允许 Claude 等 AI 助手:

  • 控制虚拟形象参数和表情

  • 在 VRChat 中发送消息

  • 响应各种VR事件
    还有更多——所有这些都通过模型上下文协议提供的高级 API 实现。

Related MCP server: Blender MCP

主要特点

  • 头像控制:操控头像参数和表情

  • 运动控制:直接控制虚拟角色的运动和方向

  • 通信:通过 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 聊天框发送消息

故障排除

常见问题

  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 链接方法

项目结构

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 实现

Available Tools

12 tools
get_avatar_listB

Get a list of available avatars.

Inputs: no named parameters.

get_avatar_nameB

Get the name of the current avatar.

Inputs: no named parameters.

get_avatar_parametersB

Get a list of parameters available on the current avatar.

Inputs: no named parameters.

jumpB

Make the avatar jump.

Inputs: no named parameters.

look_directionC

Turn to look in a specific direction.

Inputs: direction (required), duration.

move_avatarC

Move the avatar in a specific direction.

Inputs: direction (required), duration.

send_messageB

Send a message to the VRChat chatbox.

Inputs: message (required), send_immediately.

set_avatarC

Change to a specific avatar.

Inputs: avatar_id (required).

set_avatar_parameterC

Set a parameter on the current avatar.

Inputs: parameter_name (required), value (required).

set_emote_parameterC

Set VRCEmote on the current avatar.

Inputs: value (required).

voiceC

Toggle voice

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some potential overlap between 'move_avatar' and 'look_direction' for avatar movement/positioning, and 'set_avatar_parameter' and 'set_emote_parameter' both involve parameter setting. The descriptions help clarify differences, but an agent might occasionally confuse these pairs.

    Naming Consistency4/5

    The naming follows a consistent verb_noun pattern (e.g., get_avatar_list, set_avatar_parameter) with minor deviations like 'jump' and 'voice' being single words instead of verb_noun pairs. Overall, it's readable and mostly predictable, though not perfectly uniform.

    Tool Count5/5

    With 12 tools, this is well-scoped for controlling VRChat avatars via OSC. Each tool serves a clear purpose, such as avatar management, movement, communication, and parameter control, without feeling excessive or insufficient for the domain.

    Completeness4/5

    The toolset covers key aspects like avatar selection, movement, communication, and parameter control, but there are minor gaps such as missing tools for advanced interactions (e.g., gesture controls or environment manipulation). However, agents can likely work around these with the provided tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      A Model Context Protocol server that allows AI assistants to interact with the VRChat API, enabling retrieval of user information, friends lists, and other VRChat data through a standardized interface.
      18
      54 npm
      71
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects Blender to AI assistants through the Model Context Protocol, enabling direct AI control of 3D modeling, scene creation, and manipulation via natural language.
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Connects Blender 3D to AI assistants via the Model Context Protocol, enabling natural language driven 3D scene creation, manipulation, and rendering.
      15
      MIT