VRChat MCP

Servidor MCP para amigos, mundos, grupos, eventos, notificações, status, avatares e histórico do VRCX no VRChat.

Documentação

VRChat MCP

Ferramentas locais não oficiais do Model Context Protocol para amigos, mundos, grupos, eventos, notificações, status, convites e histórico local do VRCX no VRChat.

O VRChat MCP roda localmente via stdio por padrão e também oferece um modo HTTP Streamable opcional, restrito a loopback. Seus cookies de autenticação do VRChat permanecem na sua máquina e, por padrão, ficam no chaveiro do sistema operacional, com armazenamento em arquivo como fallback quando não há backend de chaveiro disponível. Ferramentas de escrita selecionadas, ferramentas de leitura/escrita geradas e ferramentas somente leitura do histórico local do VRCX estão disponíveis por padrão; use seu cliente MCP ou agente para aprovar chamadas de ferramentas que alteram a conta.

Este projeto não é oficial e não é afiliado à VRChat Inc.

Limites de Política e Segurança

O VRChat não fornece um fluxo OAuth público para aplicações de API de terceiros. As Diretrizes para Criadores do VRChat afirmam que aplicações de API não devem solicitar ou armazenar credenciais de login, tokens de autenticação ou dados de sessão do VRChat, devem se identificar com um User-Agent claro, devem usar cache/backoff em vez de enviar requisições sem limite e não devem agir em nome de outro usuário.

Este projeto, portanto, destina-se apenas a uma ferramenta pessoal local e controlada pelo usuário. Não o execute como um serviço MCP hospedado/público, não colete credenciais ou cookies de terceiros, não automatize spam ou assédio e não o use para burlar a aplicação ou moderação do VRChat. Use ferramentas de escrita apenas para ações que você realizaria intencionalmente no VRChat.

Instalação

Requisitos:

Node.js 24.15.0 ou mais recente.
Um cliente MCP que possa executar servidores stdio locais.
Dependências nativas são instaladas para suporte a keychain e SQLite do VRCX (keytar, better-sqlite3).

Em Linux headless ou contêineres sem um daemon de keychain como libsecret, defina VRCHAT_MCP_COOKIE_STORE=file para armazenamento explícito e persistente de cookies.

O pacote npm é o caminho normal de instalação:

npx -y @basicbit/vrchat-mcp

O servidor também é publicado no Registro MCP oficial como io.github.BASIC-BIT/vrchat-mcp.

Configuração do Cliente MCP

A maioria dos clientes usa uma destas formas. Nenhuma variável de ambiente é necessária para a configuração padrão.

OpenCode

O OpenCode usa um campo command com valor de array.

Adicione isto a ~/.config/opencode/opencode.json:

{
  "mcp": {
    "vrchat": {
      "type": "local",
      "command": ["npx", "-y", "@basicbit/vrchat-mcp"],
      "enabled": true
    }
  }
}

Claude Desktop, Cursor, Kiro, Roo, Windsurf

Esses clientes geralmente dividem o executável em command mais args.

Use isto em clientes que esperam um objeto mcpServers:

{
  "mcpServers": {
    "vrchat": {
      "command": "npx",
      "args": ["-y", "@basicbit/vrchat-mcp"]
    }
  }
}

VS Code

O VS Code usa um objeto servers em vez de mcpServers.

Use isto em .vscode/mcp.json:

{
  "servers": {
    "vrchat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@basicbit/vrchat-mcp"]
    }
  }
}

OpenAI Codex

Adicione isto a ~/.codex/config.toml ou .codex/config.toml:

[mcp_servers.vrchat]
command = "npx"
args = ["-y", "@basicbit/vrchat-mcp"]
startup_timeout_sec = 40

Se o seu cliente Windows não conseguir iniciar npx diretamente, use cmd como comando e coloque /c, npx, -y e @basicbit/vrchat-mcp na lista de argumentos.

HTTP Streamable Local

Use HTTP Streamable nativo quando um cliente MCP precisar se conectar a um servidor local de longa duração em vez de iniciar seu próprio processo filho stdio. STDIO continua sendo a configuração padrão e recomendada para clientes desktop comuns.

Modo HTTP:

Vincula-se apenas a 127.0.0.1.
Usa o endpoint MCP http://127.0.0.1:8765/mcp por padrão.
Exige Authorization: Bearer <token> em cada requisição MCP.
Suporta sessões com estado, notificações SSE, assinaturas de recursos e encerramento de sessão.
Encerra sessões abandonadas após 30 minutos de inatividade, preservando fluxos de resposta ativos.
Compartilha um único login, cache e conexão de pipeline local do VRChat entre todos os clientes HTTP conectados.
Não é um modo hospedado ou multiusuário.

Gere um segredo e inicie o servidor no PowerShell:

$env:VRCHAT_MCP_HTTP_BEARER_TOKEN = node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
npx -y @basicbit/vrchat-mcp --transport http

Em seguida, configure o cliente MCP para usar http://127.0.0.1:8765/mcp e envie o token de VRCHAT_MCP_HTTP_BEARER_TOKEN como um token bearer. Mantenha o token em uma variável de ambiente ou cofre de segredos; não o coloque em uma URL nem o envie para uma configuração de cliente.

Substituições de CLI:

npx -y @basicbit/vrchat-mcp --transport http --port 9000 --path /vrchat-mcp

O listener HTTP deliberadamente não pode vincular-se a uma interface LAN ou pública. Hospedagem pública permanece sem suporte porque o VRChat não fornece o modelo de isolamento de conta/OAuth necessário para um serviço de conta pessoal hospedado.

Login

Após adicionar o servidor ao seu cliente MCP, peça para ele chamar vrchat_auth_begin. A ferramenta retorna uma URL de login do navegador local.

Após fazer login, chame vrchat_auth_status para confirmar a sessão. Por padrão, os cookies são armazenados no chaveiro do sistema operacional para que o login sobreviva a reinicializações do servidor MCP. Se o chaveiro do sistema operacional não estiver disponível, o VRChat MCP usa armazenamento em arquivo como fallback.

Não peça a outra pessoa para usar este fluxo de login por você. Não envie a URL de login local, cookies ou arquivos de sessão para ferramentas hospedadas ou serviços de terceiros.

Ferramentas de autenticação úteis:

vrchat_auth_begin: inicia o login no navegador local.
vrchat_auth_status: verifica se o servidor está conectado.
vrchat_auth_logout: limpa a sessão armazenada.

Login Headless para Contas de Bot

O login no navegador precisa de uma pessoa. O cookie twoFactorAuth do VRChat dura 30 dias, e alterar o método de 2FA de uma conta revoga sua sessão imediatamente, então uma implantação não supervisionada precisaria que alguém fizesse login novamente a cada vez. Para uma conta que você possui e opera com 2FA de autenticador (TOTP), como uma conta de bot dedicada, o servidor pode fazer login novamente sozinho.

Defina todas as três variáveis para ativar. Se alguma delas estiver ausente ou vazia, nada muda.

Variável	Uso
`VRCHAT_MCP_USERNAME`	Nome de usuário ou e-mail do VRChat.
`VRCHAT_MCP_PASSWORD`	Senha do VRChat.
`VRCHAT_MCP_TOTP_SECRET`	Segredo do autenticador Base32. A forma minúscula agrupada por espaços do VRChat também é aceita.

Quando uma requisição à API do VRChat retorna 401, o servidor faz login uma vez com a senha e um código TOTP recém-gerado, salva os novos cookies no armazenamento de cookies configurado e tenta a requisição novamente uma vez. Se o VRChat pedir um código de e-mail em vez de TOTP, o servidor não envia código e retorna o erro 401 normal com uma nota para usar vrchat_auth_begin. O VRChat só revela o método de 2FA após a etapa da senha, então isso ainda conta como uma tentativa falha para o backoff abaixo.

Logins automáticos são limitados por taxa, e o limite é persistido para valer quando o host inicia um novo processo de servidor para cada chamada:

No máximo uma tentativa automática a cada 10 minutos.
Após uma tentativa falha (senha errada, código rejeitado, erro do VRChat), nenhuma tentativa automática por 60 minutos. Uma tentativa que nunca registrou um resultado, por exemplo porque o processo foi encerrado no meio do login, conta como falha.
Durante o cooldown, o erro da ferramenta informa isso e dá o horário da próxima tentativa permitida.
O registro é <cookie file>.autologin.json (modo 0600), ao lado do caminho do arquivo de cookies configurado. O armazenamento em keychain usa o mesmo caminho. Um arquivo .lock de curta duração impede que dois processos reivindiquem a mesma tentativa. Se o registro não puder ser gravado, o servidor não tenta fazer login.
Com VRCHAT_MCP_COOKIE_STORE=memory não há arquivo, então o limite fica na memória e só se aplica dentro de um processo. Isso é muito mais fraco: com um processo por chamada, todo processo faria login. Use armazenamento file para implantações headless.

A senha, o segredo TOTP, os códigos gerados e os valores de cookie nunca são registrados nem incluídos em resultados ou erros de ferramentas. vrchat_auth_logout ainda limpa a sessão, mas enquanto as variáveis estiverem definidas, a próxima chamada de API fará login novamente.

Alguns hosts MCP, incluindo o OpenClaw, substituem o ambiente do filho pelo bloco env da entrada do servidor em vez de mesclá-lo ao próprio ambiente. Não coloque a senha ou o segredo TOTP inline na configuração do host. Mantenha-os em um arquivo de ambiente de propriedade do root com modo 0600 e aponte o host para um pequeno script wrapper que carrega o arquivo e executa o servidor. O host deve executar o wrapper como um usuário que possa ler o arquivo. Coloque entre aspas valores que contenham metacaracteres de shell. Se o bloco env do host não passar PATH, defina-o no wrapper ou use caminhos absolutos.

#!/bin/sh
# /usr/local/bin/vrchat-mcp-bot
set -a
. /etc/vrchat-mcp/bot.env
set +a
exec vrchat-mcp "$@"

# /etc/vrchat-mcp/bot.env (owner root, mode 0600)
VRCHAT_MCP_COOKIE_STORE=file
VRCHAT_MCP_COOKIE_FILE=/var/lib/vrchat-mcp/cookies.json
VRCHAT_MCP_USERNAME='bot-account'
VRCHAT_MCP_PASSWORD='...'
VRCHAT_MCP_TOTP_SECRET='abcd efgh ijkl mnop qrst uvwx yz23 4567'

O Que Você Pode Perguntar

Exemplos:

Show my VRChat status and current location.

Which friends are online, grouped by world?

Search my friends for Alice and show their profile.

Find public VRChat events happening today.

Invite Bob to my current instance.

Show recent worlds from my local VRCX history.

Ferramentas

O VRChat MCP expõe ferramentas selecionadas além de roteadores gerados de leitura/escrita/exclusão por padrão. Ferramentas selecionadas cobrem tarefas comuns com entradas e saídas compactas e amigáveis para agentes.

Ferramentas selecionadas comuns incluem:

vrchat_me
vrchat_friends_overview
vrchat_friends_search
vrchat_friend_details
vrchat_worlds_search
vrchat_group_profile
vrchat_events_upcoming
vrchat_notifications_recent
vrchat_instance_link_event
vrchat_gallery_image_upload
vrchat_invite
vrchat_group_invite
vrchat_friend_request
vrchat_boop
vrcx_instances_recent

A cobertura gerada de lacunas da API OpenAPI usa três ferramentas de roteador:

vrchat_read para operações GET disponíveis; passe operationId mais valores de path/query/header/cookie sob params.
vrchat_write para operações POST/PUT/PATCH disponíveis; passe operationId, params e payloads JSON sob body.
vrchat_delete para operações DELETE disponíveis; passe operationId, params e payloads JSON opcionais sob body.

Use vrchat_operations para listar IDs de operação gerados disponíveis e vrchat_operation_details para esquemas exatos de parâmetros/corpo por operação.

Ferramentas geradas de leitura e escrita são habilitadas por padrão. VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=true oculta vrchat_read. VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=true oculta tanto vrchat_write quanto vrchat_delete, que compartilham o interruptor de escrita gerada. A configuração JSON também pode restringir qualquer superfície a IDs de operação específicos; generatedWriteTools.operationIds cobre operações DELETE também, então uma lista contendo apenas IDs POST/PUT/PATCH também oculta vrchat_delete:

{
  "generatedReadTools": { "enabled": true, "operationIds": ["getAvatarStyles"] },
  "generatedWriteTools": { "enabled": true, "operationIds": ["selectAvatar"] }
}

Quando uma lista operationIds está vazia e essa classe de ferramenta gerada está habilitada, todas as operações geradas nessa classe estão disponíveis através de seu roteador, exceto operações com skip forçado e operações com substituições selecionadas. Prefira ferramentas selecionadas para fluxos de trabalho comuns, mas os roteadores gerados mantêm o servidor local capaz conforme a API do VRChat evolui, sem duplicar a cobertura selecionada conhecida ou expor endpoints gerados que este cliente não pode chamar de forma confiável.

Veja docs/tools-guide.md para um guia curto e docs/tools.md para o catálogo gerado.

Controles de Escrita

Ferramentas de escrita selecionadas e ferramentas de escrita geradas para lacunas de API são habilitadas por padrão para que o servidor MCP local seja utilizável desde a primeira execução. Espera-se que seu cliente MCP ou agente controle permissão, aprovação e negação de chamadas de ferramentas para ações que alteram a conta.

Para forçar o modo somente leitura, adicione este fragmento env dentro da entrada do servidor para seu cliente MCP:

{
  "env": {
    "VRCHAT_MCP_ALLOW_WRITES": "false"
  }
}

Use ferramentas de escrita apenas quando você pretende que este servidor MCP local execute ações de conta do VRChat. Ferramentas sociais em massa têm limites e fazem backoff em 429s, mas você é responsável por evitar spam, assédio ou automação indesejada.

vrchat_gallery_image_upload envia um PNG estático validado para a galeria pessoal da conta conectada. Aceita apenas imagePath; a autorização de grupo é aplicada depois pela ferramenta de postagem de grupo ou evento que anexa o ID de arquivo retornado. Configure pelo menos uma entrada uploads.allowedRoots absoluta antes de usá-la.

Para ferramentas de escrita de grupo, você pode restringir escritas a IDs de grupo específicos com um arquivo de configuração JSON:

{
  "groups": {
    "allowlist": ["grp_abc123"]
  }
}

Em seguida, defina VRCHAT_MCP_CONFIG_FILE para esse caminho de arquivo na configuração do seu cliente MCP.

Configuração

A configuração é opcional. Os padrões cobrem o uso local normal.

Variáveis de ambiente comuns:

Variável	Uso
`VRCHAT_MCP_CONFIG_FILE`	Caminho para um arquivo de configuração JSON.
`VRCHAT_MCP_USER_AGENT`	User agent descritivo para requisições à API do VRChat.
`VRCHAT_MCP_LOG_LEVEL`	`debug`, `info`, `warn` ou `error`.
`VRCHAT_MCP_COOKIE_STORE`	`keychain`, `file` ou `memory`. O padrão é `keychain`.
`VRCHAT_MCP_COOKIE_FILE`	Caminho do arquivo de cookies quando `VRCHAT_MCP_COOKIE_STORE=file`.
`VRCHAT_MCP_USERNAME`	Nome de usuário para login headless.
`VRCHAT_MCP_PASSWORD`	Senha para login headless.
`VRCHAT_MCP_TOTP_SECRET`	Segredo TOTP em Base32 para login headless.
`VRCHAT_MCP_ALLOW_WRITES`	Defina como `false` para o modo somente leitura.
`VRCHAT_MCP_UPLOAD_ROOTS`	Raízes absolutas permitidas para uploads locais de PNG.
`VRCHAT_MCP_TRANSPORT`	`stdio` (padrão) ou `http`.
`VRCHAT_MCP_HTTP_BEARER_TOKEN`	Segredo obrigatório de 32+ caracteres para o modo HTTP.
`VRCHAT_MCP_HTTP_PORT`	Porta HTTP de loopback. O padrão é `8765`.
`VRCHAT_MCP_HTTP_PATH`	Caminho do endpoint MCP. O padrão é `/mcp`.
`VRCHAT_MCP_HTTP_MAX_SESSIONS`	Máximo de sessões HTTP simultâneas. O padrão é `8`.
`VRCHAT_MCP_HTTP_RATE_LIMIT_PER_MINUTE`	Limite de requisições HTTP por cliente. O padrão é `300`.
`VRCHAT_MCP_HTTP_SESSION_IDLE_TIMEOUT_MS`	Tempo limite de sessões abandonadas. O padrão é `1800000`.

Exemplo de configuração JSON:

{
  "auth": { "cookieStore": "file" },
  "writes": { "allow": false },
  "http": {
    "port": 8765,
    "path": "/mcp",
    "maxSessions": 8,
    "rateLimitPerMinute": 300,
    "sessionIdleTimeoutMs": 1800000
  },
  "groups": { "allowlist": ["grp_abc123"] },
  "uploads": { "allowedRoots": ["C:\\Users\\you\\Pictures\\VRChat Uploads"] },
  "cache": { "enabled": true },
  "vrcx": { "enabled": true }
}

Consulte src/config/defaults.json para todos os padrões.

Desenvolvimento Local

git clone https://github.com/BASIC-BIT/vrchat-mcp.git
cd vrchat-mcp
npm install
npm run build
npm run check

Scripts úteis:

npm run dev: execute a partir de src/index.ts.
npm run start: execute o servidor compilado a partir de dist/.
npm run dev -- --transport http: execute o servidor HTTP Streamable local a partir do código-fonte.
npm run start -- --transport http: execute o servidor HTTP Streamable local compilado.
npm run mcp:login: inicie o login por meio do harness local.
npm run mcp:status: verifique a autenticação por meio do harness local.
npm run smoke:live: execute a verificação de fumaça ao vivo opcional.
npm run generate:tools-docs: regenere docs/tools.md.
npm run generate:schemas: regenere os esquemas OpenAPI.
npm run mcpb:build: compile um pacote MCPB local em mcpb/.

Testes E2E ao vivo e avaliações de LLM são opcionais. Consulte docs/evals.md para detalhes.

Licença

MIT. Consulte LICENSE.