VRChat MCP

Servidor MCP para amigos, mundos, grupos, eventos, notificaciones, estado, avatares e historial de VRCX en VRChat.

GitHub
3

Documentación

VRChat MCP logo

VRChat MCP

Herramientas locales no oficiales del Model Context Protocol para amigos, mundos, grupos, eventos, notificaciones, estado, invitaciones e historial local de VRCX en VRChat.

npm license

VRChat MCP se ejecuta localmente a través de stdio de forma predeterminada y también ofrece un modo HTTP Streamable opcional de solo bucle local. Tus cookies de autenticación de VRChat permanecen en tu máquina y, de forma predeterminada, se guardan en el llavero de tu sistema operativo, con almacenamiento en archivos como alternativa cuando no hay un backend de llavero disponible. Las herramientas de escritura seleccionadas, las herramientas de lectura/escritura generadas y las herramientas de historial local de VRCX de solo lectura están disponibles de forma predeterminada; usa tu cliente MCP o entorno de agente para aprobar las llamadas a herramientas que cambian la cuenta.

Este proyecto no es oficial y no está afiliado a VRChat Inc.

Límites de Política y Seguridad

VRChat no proporciona un flujo OAuth público para aplicaciones API de terceros. Las Directrices para Creadores de VRChat indican que las aplicaciones API no deben solicitar ni almacenar credenciales de inicio de sesión, tokens de autenticación o datos de sesión de VRChat, deben identificarse con un User-Agent claro, deben almacenar en caché o retroceder en lugar de enviar solicitudes sin medir, y no deben actuar en nombre de otro usuario.

Por lo tanto, este proyecto está destinado únicamente como una herramienta personal local controlada por el usuario. No lo ejecutes como un servicio MCP alojado/público, no recopiles credenciales o cookies de otras personas, no automatices spam o acoso, y no lo uses para evadir la aplicación o moderación de VRChat. Usa las herramientas de escritura solo para acciones que realizarías intencionalmente tú mismo en VRChat.

Instalación

Requisitos:

  • Node.js 24.15.0 o superior.
  • Un cliente MCP que pueda ejecutar servidores stdio locales.
  • Las dependencias nativas se instalan para el soporte de llavero y SQLite de VRCX (keytar, better-sqlite3).

En Linux sin interfaz gráfica o contenedores sin un daemon de llavero como libsecret, establece VRCHAT_MCP_COOKIE_STORE=file para el almacenamiento explícito de cookies persistente.

El paquete npm es la ruta de instalación normal:

npx -y @basicbit/vrchat-mcp

El servidor también se publica en el Registro MCP oficial como io.github.BASIC-BIT/vrchat-mcp.

Configuración del Cliente MCP

La mayoría de los clientes usan una de estas formas. No se requieren variables de entorno para la configuración predeterminada.

OpenCode

OpenCode usa un campo command con valor de matriz.

Agrega esto a ~/.config/opencode/opencode.json:

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

Claude Desktop, Cursor, Kiro, Roo, Windsurf

Estos clientes generalmente dividen el ejecutable en command más args.

Usa esto en clientes que esperan un objeto mcpServers:

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

VS Code

VS Code usa un objeto servers en lugar de mcpServers.

Usa esto en .vscode/mcp.json:

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

OpenAI Codex

Agrega esto a ~/.codex/config.toml o .codex/config.toml:

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

Si tu cliente de Windows no puede iniciar npx directamente, usa cmd como comando y coloca /c, npx, -y y @basicbit/vrchat-mcp en la lista de argumentos.

HTTP Streamable Local

Usa HTTP Streamable nativo cuando un cliente MCP necesite conectarse a un servidor local de larga duración en lugar de iniciar su propio proceso hijo stdio. STDIO sigue siendo la configuración predeterminada y recomendada para clientes de escritorio comunes.

Modo HTTP:

  • Se vincula solo a 127.0.0.1.
  • Usa el endpoint MCP http://127.0.0.1:8765/mcp de forma predeterminada.
  • Requiere Authorization: Bearer <token> en cada solicitud MCP.
  • Admite sesiones con estado, notificaciones SSE, suscripciones a recursos y terminación de sesiones.
  • Recolecta sesiones abandonadas después de 30 minutos de inactividad mientras preserva los flujos de respuesta activos.
  • Comparte un único inicio de sesión local de VRChat, caché y conexión de canalización entre todos los clientes HTTP conectados.
  • No es un modo alojado o multiusuario.

Genera un secreto e inicia el servidor en 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

Luego configura el cliente MCP para usar http://127.0.0.1:8765/mcp y envía el token de VRCHAT_MCP_HTTP_BEARER_TOKEN como token de portador. Mantén el token en una variable de entorno o almacén de secretos; no lo pongas en una URL ni lo confirmes en una configuración de cliente.

Anulaciones de CLI:

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

El listener HTTP deliberadamente no puede vincularse a una interfaz LAN o pública. El alojamiento público sigue sin ser compatible porque VRChat no proporciona el modelo de aislamiento de cuenta/OAuth necesario para un servicio de cuenta personal alojado.

Inicio de Sesión

Después de agregar el servidor a tu cliente MCP, pídele que llame a vrchat_auth_begin. La herramienta devuelve una URL de inicio de sesión del navegador local.

Después de iniciar sesión, llama a vrchat_auth_status para confirmar la sesión. De forma predeterminada, las cookies se almacenan en el llavero del sistema operativo para que el inicio de sesión sobreviva a los reinicios del servidor MCP. Si el llavero del sistema operativo no está disponible, VRChat MCP recurre al almacenamiento en archivos.

No pidas a otra persona que use este flujo de inicio de sesión por ti. No envíes la URL de inicio de sesión local, cookies o archivos de sesión a herramientas alojadas o servicios de terceros.

Herramientas de autenticación útiles:

  • vrchat_auth_begin: inicia el inicio de sesión del navegador local.
  • vrchat_auth_status: verifica si el servidor ha iniciado sesión.
  • vrchat_auth_logout: borra la sesión almacenada.

Inicio de Sesión sin Interfaz Gráfica para Cuentas de Bot

El inicio de sesión del navegador necesita una persona. La cookie twoFactorAuth de VRChat dura 30 días, y cambiar el método 2FA de una cuenta revoca su sesión inmediatamente, por lo que una implementación desatendida necesitaría que alguien inicie sesión nuevamente cada vez. Para una cuenta que posees y operas con 2FA de autenticador (TOTP), como una cuenta de bot dedicada, el servidor puede iniciar sesión automáticamente.

Establece las tres variables para activarlo. Si falta alguna o está vacía, no cambia nada.

VariableUso
VRCHAT_MCP_USERNAMENombre de usuario o correo electrónico de VRChat.
VRCHAT_MCP_PASSWORDContraseña de VRChat.
VRCHAT_MCP_TOTP_SECRETSecreto del autenticador Base32. También se acepta la forma en minúsculas agrupada por espacios de VRChat.

Cuando una solicitud API de VRChat devuelve 401, el servidor inicia sesión una vez con la contraseña y un código TOTP recién generado, guarda las nuevas cookies en el almacén de cookies configurado y reintenta la solicitud una vez. Si VRChat solicita un código de correo electrónico en lugar de TOTP, el servidor no envía ningún código y devuelve el error 401 normal con una nota para usar vrchat_auth_begin. VRChat solo revela el método 2FA después del paso de la contraseña, por lo que eso aún cuenta como un intento fallido para la limitación a continuación.

Los inicios de sesión automáticos tienen límite de velocidad, y el límite se persiste para que se mantenga cuando el host inicia un nuevo proceso de servidor para cada llamada:

  • Como máximo un intento automático cada 10 minutos.
  • Después de un intento fallido (contraseña incorrecta, código rechazado, error de VRChat), no hay intento automático durante 60 minutos. Un intento que nunca registró un resultado, por ejemplo porque el proceso se eliminó a mitad del inicio de sesión, cuenta como fallido.
  • Durante el período de espera, el error de la herramienta lo indica y da la hora del próximo intento permitido.
  • El registro es <cookie file>.autologin.json (modo 0600), junto a la ruta del archivo de cookies configurado. El almacenamiento en llavero usa la misma ruta. Un archivo .lock de corta duración evita que dos procesos reclamen el mismo intento. Si el registro no se puede escribir, el servidor no intenta iniciar sesión.
  • Con VRCHAT_MCP_COOKIE_STORE=memory no hay archivo, por lo que el límite vive en memoria y solo se aplica dentro de un proceso. Eso es mucho más débil: con un proceso por llamada, cada proceso iniciaría sesión. Usa almacenamiento file para implementaciones sin interfaz gráfica.

La contraseña, el secreto TOTP, los códigos generados y los valores de cookies nunca se registran ni se incluyen en resultados o errores de herramientas. vrchat_auth_logout aún borra la sesión, pero mientras las variables estén establecidas, la próxima llamada API iniciará sesión nuevamente.

Algunos hosts MCP, incluido OpenClaw, reemplazan el entorno del hijo con el bloque env de la entrada del servidor en lugar de fusionarlo con el suyo propio. No pongas la contraseña o el secreto TOTP en línea en la configuración del host. Mantenlos en un archivo de entorno propiedad de root con modo 0600 y apunta el host a un pequeño script contenedor que cargue el archivo y ejecute el servidor. El host debe ejecutar el contenedor como un usuario que pueda leer el archivo. Cita los valores que contengan metacaracteres de shell. Si el bloque env del host no pasa PATH, configúralo en el contenedor o usa rutas absolutas.

#!/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'

Lo Que Puedes Preguntar

Ejemplos:

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.

Herramientas

VRChat MCP expone herramientas seleccionadas más enrutadores de lectura/escritura/eliminación generados de forma predeterminada. Las herramientas seleccionadas cubren tareas comunes con entradas y salidas compactas y amigables para agentes.

Las herramientas seleccionadas comunes incluyen:

  • 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

La cobertura generada de brechas de API OpenAPI usa tres herramientas de enrutador:

  • vrchat_read para operaciones GET disponibles; pasa operationId más valores de ruta/consulta/encabezado/cookie bajo params.
  • vrchat_write para operaciones POST/PUT/PATCH disponibles; pasa operationId, params y cargas JSON bajo body.
  • vrchat_delete para operaciones DELETE disponibles; pasa operationId, params y cargas JSON opcionales bajo body.

Usa vrchat_operations para listar los IDs de operación generados disponibles y vrchat_operation_details para los esquemas exactos de parámetros/cuerpo por operación.

Las herramientas de lectura y escritura generadas están habilitadas de forma predeterminada. VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=true oculta vrchat_read. VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=true oculta tanto vrchat_write como vrchat_delete, que comparten el interruptor de escritura generada. La configuración JSON también puede reducir cualquiera de las superficies a IDs de operación específicos; generatedWriteTools.operationIds cubre también las operaciones DELETE, por lo que una lista que contenga solo IDs POST/PUT/PATCH también oculta vrchat_delete:

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

Cuando una lista operationIds está vacía y esa clase de herramienta generada está habilitada, todas las operaciones generadas en esa clase están disponibles a través de su enrutador, excepto las operaciones omitidas forzosamente y las operaciones con reemplazos seleccionados. Prefiere las herramientas seleccionadas para flujos de trabajo comunes, pero los enrutadores generados mantienen el servidor local capaz a medida que la API de VRChat evoluciona sin duplicar la cobertura seleccionada conocida ni exponer endpoints generados que este cliente no puede llamar de manera confiable.

Consulta docs/tools-guide.md para una guía breve y docs/tools.md para el catálogo generado.

Controles de Escritura

Las herramientas de escritura seleccionadas y las herramientas de escritura generadas para brechas de API están habilitadas de forma predeterminada para que el servidor MCP local sea utilizable desde la primera ejecución. Se espera que tu cliente MCP o entorno de agente controle el permiso, la aprobación y la denegación de llamadas a herramientas para acciones que cambian la cuenta.

Para forzar el modo de solo lectura, agrega este fragmento env dentro de la entrada del servidor para tu cliente MCP:

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

Solo usa herramientas de escritura cuando tengas la intención de que este servidor MCP local realice acciones de cuenta de VRChat. Las herramientas sociales masivas tienen un límite y retroceden en 429s, pero eres responsable de evitar spam, acoso o automatización no deseada.

vrchat_gallery_image_upload sube un PNG estático validado a la galería personal de la cuenta con sesión iniciada. Solo acepta imagePath; la autorización de grupo se aplica más tarde por la herramienta de publicación o evento de grupo que adjunta el ID de archivo devuelto. Configura al menos una entrada uploads.allowedRoots absoluta antes de usarla.

Para herramientas de escritura de grupo, puedes restringir las escrituras a IDs de grupo específicos con un archivo de configuración JSON:

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

Luego establece VRCHAT_MCP_CONFIG_FILE a esa ruta de archivo en la configuración de tu cliente MCP.

Configuración

La configuración es opcional. Los valores predeterminados cubren el uso local normal.

Variables de entorno comunes:

VariableUso
VRCHAT_MCP_CONFIG_FILERuta a un archivo de configuración JSON.
VRCHAT_MCP_USER_AGENTAgente de usuario descriptivo para solicitudes a la API de VRChat.
VRCHAT_MCP_LOG_LEVELdebug, info, warn o error.
VRCHAT_MCP_COOKIE_STOREkeychain, file o memory. El valor predeterminado es keychain.
VRCHAT_MCP_COOKIE_FILERuta del archivo de cookies cuando VRCHAT_MCP_COOKIE_STORE=file.
VRCHAT_MCP_USERNAMENombre de usuario para inicio de sesión sin interfaz.
VRCHAT_MCP_PASSWORDContraseña para inicio de sesión sin interfaz.
VRCHAT_MCP_TOTP_SECRETSecreto TOTP en Base32 para inicio de sesión sin interfaz.
VRCHAT_MCP_ALLOW_WRITESEstablézcalo en false para el modo de solo lectura.
VRCHAT_MCP_UPLOAD_ROOTSRaíces absolutas permitidas para subidas de PNG locales.
VRCHAT_MCP_TRANSPORTstdio (predeterminado) o http.
VRCHAT_MCP_HTTP_BEARER_TOKENSecreto requerido de 32+ caracteres para el modo HTTP.
VRCHAT_MCP_HTTP_PORTPuerto HTTP de bucle local. El valor predeterminado es 8765.
VRCHAT_MCP_HTTP_PATHRuta del endpoint MCP. El valor predeterminado es /mcp.
VRCHAT_MCP_HTTP_MAX_SESSIONSMáximo de sesiones HTTP concurrentes. El valor predeterminado es 8.
VRCHAT_MCP_HTTP_RATE_LIMIT_PER_MINUTELímite de solicitudes HTTP por cliente. El valor predeterminado es 300.
VRCHAT_MCP_HTTP_SESSION_IDLE_TIMEOUT_MSTiempo de espera para sesiones abandonadas. El valor predeterminado es 1800000.

Ejemplo de configuración 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 los valores predeterminados.

Desarrollo Local

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

Scripts útiles:

  • npm run dev: ejecutar desde src/index.ts.
  • npm run start: ejecutar el servidor compilado desde dist/.
  • npm run dev -- --transport http: ejecutar el servidor HTTP Streamable local desde el código fuente.
  • npm run start -- --transport http: ejecutar el servidor HTTP Streamable local compilado.
  • npm run mcp:login: iniciar sesión a través del entorno de prueba local.
  • npm run mcp:status: verificar la autenticación a través del entorno de prueba local.
  • npm run smoke:live: ejecutar la verificación de humo en vivo opcional.
  • npm run generate:tools-docs: regenerar docs/tools.md.
  • npm run generate:schemas: regenerar esquemas OpenAPI.
  • npm run mcpb:build: compilar un paquete MCPB local en mcpb/.

Las pruebas E2E en vivo y las evaluaciones LLM son opcionales. Consulte docs/evals.md para más detalles.

Licencia

MIT. Consulte LICENSE.