VRChat MCP OSC

VRChat MCP OSC

VRChat MCP OSC proporciona un puente entre asistentes de IA y VRChat utilizando el Protocolo de Contexto de Modelos (MCP), permitiendo el control de avatares y las interacciones impulsadas por IA en entornos de realidad virtual.

Descripción general

Al aprovechar OSC (Open Sound Control) para comunicarse con VRChat, VRChat MCP OSC permite que asistentes de IA como Claude puedan:

• Controlar parámetros y expresiones del avatar
• Enviar mensajes en VRChat
• Responder a diversos eventos de realidad virtual Y más—todo a través de la API de alto nivel proporcionada por el Protocolo de Contexto de Modelos.

Características principales

• Control de Avatar: Manipula parámetros y expresiones del avatar
• Control de Movimiento: Dirige el movimiento y la orientación del avatar
• Comunicación: Envía mensajes a través del chatbox de VRChat
• Acceso al Menú: Alterna el menú de VRChat y los elementos de la interfaz
• Información del Avatar: Consulta propiedades y parámetros del avatar
• Integración Perfecta con VRChat: Detección automática de configuraciones de avatar

Requisitos del sistema

• Node.js 18 o superior
• VRChat con OSC habilitado
• Claude Desktop (con soporte para MCP)

Uso con Claude Desktop

Clonar y enlazar con npm

git clone https://github.com/Krekun/vrchat-mcp-osc
cd vrchat-mcp-osc
npm link

Configurar Claude Desktop

Configura Claude Desktop editando el archivo claude_desktop_config.json:

{
  "mcpServers": {
    "vrchat-mcp-osc": {
      "command": "npx",
      "args": [
        "vrchat-mcp-osc"
      ]
    }
  }
}

Opciones de línea de comandos

El servidor admite varios argumentos de línea de comandos para personalización:

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

Opciones disponibles

Opción	Descripción	Predeterminado	Notas
--websocket-port <port>	Puerto WebSocket	8765	Para comunicación WebSocket
--websocket-host <host>	Host WebSocket	localhost	Para comunicación WebSocket
--osc-send-port <port>	Puerto de envío OSC	9000	Puerto para enviar a VRChat
--osc-send-ip <ip>	IP de envío OSC	127.0.0.1	Dirección para enviar a VRChat
--osc-receive-port <port>	Puerto de recepción OSC	9001	Puerto para recibir de VRChat
--osc-receive-ip <ip>	IP de recepción OSC	127.0.0.1	Dirección para recibir de VRChat
--debug	Habilitar registro de depuración	false	Genera registros detallados
--no-relay	Deshabilitar servidor de retransmisión	false	Cuando no se usa servidor de retransmisión

Herramientas MCP disponibles

VRChat MCP OSC expone las siguientes herramientas MCP a los asistentes de IA:

Nombre de la herramienta	Descripción
get_avatar_name	Obtiene el nombre del avatar actual
get_avatar_parameters	Lista los parámetros disponibles del avatar
set_avatar_parameter	Establece un parámetro específico del avatar
set_emote_parameter	Activa emotes del avatar
move_avatar	Mueve el avatar en una dirección específica
look_direction	Controla la dirección de visión del avatar
jump	Hace que el avatar salte
menu	Alterna el menú de VRChat
voice	Alterna las funciones de voz
send_message	Envía un mensaje al chatbox de VRChat

Solución de problemas

Problemas comunes

1. VRChat no responde a los comandos

   • Asegúrate de que OSC esté habilitado en la configuración de VRChat
   • Verifica que los puertos OSC coincidan entre VRChat y la configuración de MCP
   • Reinicia VRChat y Claude Desktop

2. El servidor MCP no se inicia

   • Asegúrate de que Node.js 18+ esté instalado
   • Revisa los argumentos de línea de comandos para detectar errores
   • Intenta ejecutar con la bandera --debug para obtener registros más detallados
   • Usa npx vrchat-mcp-osc -- --debug si los argumentos directos no funcionan

3. Problemas de ejecución con NPX

   • Si los argumentos no se reconocen, intenta usar el formato de doble guion: npx vrchat-mcp-osc -- --debug
   • En Windows, intenta ejecutar en un símbolo del sistema con privilegios de administrador
   • Si tienes problemas con la instalación global, prueba el enfoque de enlace local con npm

Estructura del proyecto

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

Desarrollo

Compilar desde el código fuente

# 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

Licencia

VRChat MCP OSC tiene doble licencia de la siguiente manera:

Para uso no comercial: Puedes usar, modificar y redistribuir el software bajo los términos de la Licencia MIT. (Consulta el archivo de la Licencia MIT para más detalles).

Para uso comercial: El uso comercial de este software requiere una licencia comercial por separado.

Al usar este software bajo la Licencia MIT para fines no comerciales, aceptas los términos de dicha licencia. Los usuarios comerciales deben obtener una licencia comercial como se describe anteriormente.

Agradecimientos

• Al equipo de VRChat por la integración OSC
• Al Protocolo de Contexto de Modelos por la interfaz de IA estandarizada
• A Anthropic por la implementación de MCP de Claude