VRChat MCP OSC

VRChat MCP OSC

VRChat MCP OSC fornece uma ponte entre assistentes de IA e o VRChat usando o Model Context Protocol (MCP), permitindo controle de avatares e interações impulsionados por IA em ambientes de realidade virtual.

Visão Geral

Ao aproveitar o OSC (Open Sound Control) para se comunicar com o VRChat, o VRChat MCP OSC permite que assistentes de IA como o Claude possam:

• Controlar parâmetros e expressões de avatares
• Enviar mensagens no VRChat
• Responder a vários eventos de VR E muito mais—tudo através da API de alto nível fornecida pelo Model Context Protocol.

Principais Recursos

• Controle de Avatar: Manipula parâmetros e expressões de avatares
• Controle de Movimento: Direciona o movimento e a orientação do avatar
• Comunicação: Envia mensagens pela caixa de chat do VRChat
• Acesso ao Menu: Alterna o menu e elementos da interface do VRChat
• Informações do Avatar: Consulta propriedades e parâmetros do avatar
• Integração Perfeita com o VRChat: Detecção automática de configurações de avatar

Requisitos do Sistema

• Node.js 18 ou superior
• VRChat com OSC habilitado
• Claude Desktop (com suporte a MCP)

Usando com o Claude Desktop

Clone e npm link

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

Configurar o Claude Desktop

Configure o Claude Desktop editando o arquivo claude_desktop_config.json:

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

Opções de Linha de Comando

O servidor suporta vários argumentos de linha de comando para personalização:

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

Opções Disponíveis

Opção	Descrição	Padrão	Observações
--websocket-port <port>	Porta WebSocket	8765	Para comunicação WebSocket
--websocket-host <host>	Host WebSocket	localhost	Para comunicação WebSocket
--osc-send-port <port>	Porta de envio OSC	9000	Porta para envio ao VRChat
--osc-send-ip <ip>	IP de envio OSC	127.0.0.1	Endereço para envio ao VRChat
--osc-receive-port <port>	Porta de recebimento OSC	9001	Porta para recebimento do VRChat
--osc-receive-ip <ip>	IP de recebimento OSC	127.0.0.1	Endereço para recebimento do VRChat
--debug	Habilitar registro de depuração	false	Exibe logs detalhados
--no-relay	Desabilitar servidor de retransmissão	false	Quando não estiver usando servidor de retransmissão

Ferramentas MCP Disponíveis

O VRChat MCP OSC expõe as seguintes ferramentas MCP aos assistentes de IA:

Nome da Ferramenta	Descrição
get_avatar_name	Recupera o nome do avatar atual
get_avatar_parameters	Lista os parâmetros de avatar disponíveis
set_avatar_parameter	Define um parâmetro específico do avatar
set_emote_parameter	Aciona emotes do avatar
move_avatar	Move o avatar em uma direção específica
look_direction	Controla a direção de visão do avatar
jump	Faz o avatar pular
menu	Alterna o menu do VRChat
voice	Alterna recursos de voz
send_message	Envia uma mensagem para a caixa de chat do VRChat

Solução de Problemas

Problemas Comuns

1. VRChat não respondendo aos comandos

   • Certifique-se de que o OSC está habilitado nas configurações do VRChat
   • Verifique se as portas OSC coincidem entre a configuração do VRChat e do MCP
   • Reinicie o VRChat e o Claude Desktop

2. Servidor MCP não iniciando

   • Certifique-se de que o Node.js 18+ está instalado
   • Verifique os argumentos de linha de comando para erros
   • Tente executar com a flag --debug para logs mais detalhados
   • Use npx vrchat-mcp-osc -- --debug se os argumentos diretos não funcionarem

3. Problemas de execução com NPX

   • Se os argumentos não estiverem sendo reconhecidos, tente usar o formato de travessão duplo: npx vrchat-mcp-osc -- --debug
   • No Windows, tente executar em um prompt de comando com privilégios de administrador
   • Se estiver tendo problemas com a instalação global, tente a abordagem de npm link local

Estrutura do Projeto

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

Desenvolvimento

Compilar a Partir do Código-Fonte

# 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

Licença

O VRChat MCP OSC é licenciado duplamente da seguinte forma:

Para Uso Não Comercial: Você pode usar, modificar e redistribuir o software sob os termos da Licença MIT. (Consulte o arquivo da Licença MIT para detalhes.)

Para Uso Comercial: O uso comercial deste software requer uma licença comercial separada.

Ao usar este software sob a Licença MIT para fins não comerciais, você concorda com os termos dessa licença. Usuários comerciais devem obter uma licença comercial conforme descrito acima.

Agradecimentos

• Equipe do VRChat pela integração OSC
• Model Context Protocol pela interface de IA padronizada
• Anthropic pela implementação do MCP no Claude