VRChat MCP server

VRChat MCP

Unofficial local Model Context Protocol tools for VRChat friends, worlds, groups, events, notifications, status, invites, and local VRCX history.

VRChat MCP runs locally through stdio by default and also offers an opt-in loopback-only Streamable HTTP mode. Your VRChat auth cookies stay on your machine and default to your OS keychain, with file storage as the fallback when a keychain backend is unavailable. Curated write tools, generated read/write tools, and read-only VRCX local-history tools are available by default; use your MCP client or agent harness to approve account-changing tool calls.

This project is unofficial and is not affiliated with VRChat Inc.

Policy and Safety Boundaries

VRChat does not provide a public OAuth flow for third-party API applications. VRChat's Creator Guidelines say API applications should not request or store VRChat login credentials, auth tokens, or session data, should identify themselves with a clear User-Agent, should cache/back off instead of sending unmetered requests, and should not act on behalf of another user.

This project is therefore intended only as a local, user-controlled personal tool. Do not run it as a hosted/public MCP service, do not collect anyone else's credentials or cookies, do not automate spam or harassment, and do not use it to evade VRChat enforcement or moderation. Use write tools only for actions you would intentionally perform yourself in VRChat.

Install

Requirements:

• Node.js 24.15.0 or newer.
• An MCP client that can run local stdio servers.
• Native dependencies are installed for keychain and VRCX SQLite support (keytar, better-sqlite3).

On headless Linux or containers without a keychain daemon such as libsecret, set VRCHATMCPCOOKIE_STORE=file for explicit persistent cookie storage.

The npm package is the normal install path:

npx -y @basicbit/vrchat-mcp

The server is also published to the official MCP Registry as io.github.BASIC-BIT/vrchat-mcp.

MCP Client Config

Most clients use one of these shapes. No environment variables are required for the default setup.

OpenCode

OpenCode uses an array-valued command field.

Add this to ~/.config/opencode/opencode.json:

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

Claude Desktop, Cursor, Kiro, Roo, Windsurf

These clients usually split the executable into command plus args.

Use this in clients that expect an mcpServers object:

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

VS Code

VS Code uses a servers object instead of mcpServers.

Use this in .vscode/mcp.json:

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

OpenAI Codex

Add this to ~/.codex/config.toml or .codex/config.toml:

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

If your Windows client cannot spawn npx directly, use cmd as the command and put /c, npx, -y, and @basicbit/vrchat-mcp in the argument list.

Local Streamable HTTP

Use native Streamable HTTP when an MCP client needs to connect to a long-running local server instead of spawning its own stdio child process. STDIO remains the default and recommended setup for ordinary desktop clients.

HTTP mode:

Shortened. The full README is on GitHub.