{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.svg\" alt=\"VRChat MCP logo\" width=\"112\" height=\"112\" />\n</p>\n\n# VRChat MCP\n\nUnofficial local [Model Context Protocol](https://modelcontextprotocol.io/) tools for VRChat friends, worlds, groups, events, notifications, status, invites, and local VRCX history.\n\n[![npm](https://img.shields.io/npm/v/%40basicbit%2Fvrchat-mcp)](https://www.npmjs.com/package/@basicbit/vrchat-mcp) [![license](https://img.shields.io/npm/l/%40basicbit%2Fvrchat-mcp)](./LICENSE)\n\nVRChat 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.\n\nThis project is unofficial and is not affiliated with VRChat Inc.\n\n## Policy and Safety Boundaries\n\nVRChat 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.\n\nThis 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.\n\n## Install\n\nRequirements:\n\n- Node.js 24.15.0 or newer.\n- An MCP client that can run local stdio servers.\n- Native dependencies are installed for keychain and VRCX SQLite support (`keytar`, `better-sqlite3`).\n\nOn headless Linux or containers without a keychain daemon such as `libsecret`, set `VRCHAT_MCP_COOKIE_STORE=file` for explicit persistent cookie storage.\n\nThe npm package is the normal install path:\n\n```bash\nnpx -y @basicbit/vrchat-mcp\n```\n\nThe server is also published to the official MCP Registry as `io.github.BASIC-BIT/vrchat-mcp`.\n\n## MCP Client Config\n\nMost clients use one of these shapes. No environment variables are required for the default setup.\n\n### OpenCode\n\nOpenCode uses an array-valued `command` field.\n\nAdd this to `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"vrchat\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@basicbit/vrchat-mcp\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### Claude Desktop, Cursor, Kiro, Roo, Windsurf\n\nThese clients usually split the executable into `command` plus `args`.\n\nUse this in clients that expect an `mcpServers` object:\n\n```json\n{\n  \"mcpServers\": {\n    \"vrchat\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@basicbit/vrchat-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nVS Code uses a `servers` object instead of `mcpServers`.\n\nUse this in `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"vrchat\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@basicbit/vrchat-mcp\"]\n    }\n  }\n}\n```\n\n### OpenAI Codex\n\nAdd this to `~/.codex/config.toml` or `.codex/config.toml`:\n\n```toml\n[mcp_servers.vrchat]\ncommand = \"npx\"\nargs = [\"-y\", \"@basicbit/vrchat-mcp\"]\nstartup_timeout_sec = 40\n```\n\nIf 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.\n\n## Local Streamable HTTP\n\nUse 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.\n\nHTTP mode:\n\n- Binds only to `127.0.0.1`.\n- Uses the MCP endpoint `http://127.0.0.1:8765/mcp` by default.\n- Requires `Authorization: Bearer <token>` on every MCP request.\n- Supports stateful sessions, SSE notifications, resource subscriptions, and session termination.\n- Reaps abandoned sessions after 30 minutes of inactivity while preserving active response streams.\n- Shares one local VRChat login, cache, and pipeline connection across all connected HTTP clients.\n- Is not a hosted or multi-user mode.\n\nGenerate a secret and launch the server in PowerShell:\n\n```powershell\n$env:VRCHAT_MCP_HTTP_BEARER_TOKEN = node -e \"console.log(require('node:crypto').randomBytes(32).toString('hex'))\"\nnpx -y @basicbit/vrchat-mcp --transport http\n```\n\nThen configure the MCP client to use `http://127.0.0.1:8765/mcp` and send the token from `VRCHAT_MCP_HTTP_BEARER_TOKEN` as a bearer token. Keep the token in an environment variable or secret store; do not put it in a URL or commit it to a client configuration.\n\nCLI overrides:\n\n```powershell\nnpx -y @basicbit/vrchat-mcp --transport http --port 9000 --path /vrchat-mcp\n```\n\nThe HTTP listener deliberately cannot bind to a LAN or public interface. Public hosting remains unsupported because VRChat does not provide the OAuth/account-isolation model needed for a hosted personal-account service.\n\n## Login\n\nAfter adding the server to your MCP client, ask it to call `vrchat_auth_begin`. The tool returns a local browser login URL.\n\nAfter logging in, call `vrchat_auth_status` to confirm the session. By default, cookies are stored in the OS keychain so the login survives MCP server restarts. If the OS keychain is unavailable, VRChat MCP falls back to file storage.\n\nDo not ask another person to use this login flow for you. Do not send the local login URL, cookies, or session files to hosted tools or third-party services.\n\nUseful auth tools:\n\n- `vrchat_auth_begin`: start local browser login.\n- `vrchat_auth_status`: check whether the server is logged in.\n- `vrchat_auth_logout`: clear the stored session.\n\n## What You Can Ask\n\nExamples:\n\n```txt\nShow my VRChat status and current location.\n```\n\n```txt\nWhich friends are online, grouped by world?\n```\n\n```txt\nSearch my friends for Alice and show their profile.\n```\n\n```txt\nFind public VRChat events happening today.\n```\n\n```txt\nInvite Bob to my current instance.\n```\n\n```txt\nShow recent worlds from my local VRCX history.\n```\n\n## Tools\n\nVRChat MCP exposes curated tools plus generated read/write/delete routers by default. Curated tools cover common tasks with compact, agent-friendly inputs and outputs.\n\nCommon curated tools include:\n\n- `vrchat_me`\n- `vrchat_friends_overview`\n- `vrchat_friends_search`\n- `vrchat_friend_details`\n- `vrchat_worlds_search`\n- `vrchat_group_profile`\n- `vrchat_events_upcoming`\n- `vrchat_notifications_recent`\n- `vrchat_instance_link_event`\n- `vrchat_gallery_image_upload`\n- `vrchat_invite`\n- `vrchat_group_invite`\n- `vrchat_friend_request`\n- `vrchat_boop`\n- `vrcx_instances_recent`\n\nGenerated OpenAPI API-gap coverage uses three router tools:\n\n- `vrchat_read` for available GET operations; pass `operationId` plus path/query/header/cookie values under `params`.\n- `vrchat_write` for available POST/PUT/PATCH operations; pass `operationId`, `params`, and JSON payloads under `body`.\n- `vrchat_delete` for available DELETE operations; pass `operationId`, `params`, and optional JSON payloads under `body`.\n\nUse `vrchat_operations` to list available generated operation IDs and `vrchat_operation_details` for exact per-operation params/body schemas.\n\nGenerated read and write tools are enabled by default. `VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=true` hides `vrchat_read`. `VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=true` hides both `vrchat_write` and `vrchat_delete`, which share the generated-write switch. JSON config can also narrow either surface to specific operation IDs; `generatedWriteTools.operationIds` covers DELETE operations too, so a list holding only POST/PUT/PATCH IDs also hides `vrchat_delete`:\n\n```json\n{\n  \"generatedReadTools\": { \"enabled\": true, \"operationIds\": [\"getAvatarStyles\"] },\n  \"generatedWriteTools\": { \"enabled\": true, \"operationIds\": [\"selectAvatar\"] }\n}\n```\n\nWhen an `operationIds` list is empty and that generated tool class is enabled, all generated operations in that class are available through its router except hard-skipped operations and operations with curated replacements. Prefer curated tools for common workflows, but generated routers keep the local server capable as the VRChat API evolves without duplicating known curated coverage or exposing generated endpoints this client cannot reliably call.\n\nSee `docs/tools-guide.md` for a short guide and `docs/tools.md` for the generated catalog.\n\n## Write Controls\n\nCurated write tools and generated write tools for API gaps are enabled by default so the local MCP server is usable from the first run. Your MCP client or agent harness is expected to control tool-call permission, approval, and denial for account-changing actions.\n\nTo force read-only mode, add this `env` fragment inside the server entry for your MCP client:\n\n```json\n{\n  \"env\": {\n    \"VRCHAT_MCP_ALLOW_WRITES\": \"false\"\n  }\n}\n```\n\nOnly use write tools when you intend this local MCP server to perform VRChat account actions. Bulk social tools are capped and back off on 429s, but you are responsible for avoiding spam, harassment, or unwanted automation.\n\n`vrchat_gallery_image_upload` uploads a validated static PNG to the signed-in account's personal gallery. It accepts only `imagePath`; group authorization is enforced later by the group post or event tool that attaches the returned file ID. Configure at least one absolute `uploads.allowedRoots` entry before using it.\n\nFor group write tools, you can restrict writes to specific group IDs with a JSON config file:\n\n```json\n{\n  \"groups\": {\n    \"allowlist\": [\"grp_abc123\"]\n  }\n}\n```\n\nThen set `VRCHAT_MCP_CONFIG_FILE` to that file path in your MCP client config.\n\n## Configuration\n\nConfiguration is optional. Defaults cover normal local use.\n\nCommon environment variables:\n\n| Variable                                  | Use                                                      |\n| ----------------------------------------- | -------------------------------------------------------- |\n| `VRCHAT_MCP_CONFIG_FILE`                  | Path to a JSON config file.                              |\n| `VRCHAT_MCP_USER_AGENT`                   | Descriptive user agent for VRChat API requests.          |\n| `VRCHAT_MCP_LOG_LEVEL`                    | `debug`, `info`, `warn`, or `error`.                     |\n| `VRCHAT_MCP_COOKIE_STORE`                 | `keychain`, `file`, or `memory`. Defaults to `keychain`. |\n| `VRCHAT_MCP_COOKIE_FILE`                  | Cookie file path when `VRCHAT_MCP_COOKIE_STORE=file`.    |\n| `VRCHAT_MCP_ALLOW_WRITES`                 | Set to `false` for read-only mode.                       |\n| `VRCHAT_MCP_UPLOAD_ROOTS`                 | Absolute roots allowed for local PNG uploads.            |\n| `VRCHAT_MCP_TRANSPORT`                    | `stdio` (default) or `http`.                             |\n| `VRCHAT_MCP_HTTP_BEARER_TOKEN`            | Required 32+ character secret for HTTP mode.             |\n| `VRCHAT_MCP_HTTP_PORT`                    | Loopback HTTP port. Defaults to `8765`.                  |\n| `VRCHAT_MCP_HTTP_PATH`                    | MCP endpoint path. Defaults to `/mcp`.                   |\n| `VRCHAT_MCP_HTTP_MAX_SESSIONS`            | Maximum concurrent HTTP sessions. Defaults to `8`.       |\n| `VRCHAT_MCP_HTTP_RATE_LIMIT_PER_MINUTE`   | Per-client HTTP request limit. Defaults to `300`.        |\n| `VRCHAT_MCP_HTTP_SESSION_IDLE_TIMEOUT_MS` | Abandoned-session timeout. Defaults to `1800000`.        |\n\nExample JSON config:\n\n```json\n{\n  \"auth\": { \"cookieStore\": \"file\" },\n  \"writes\": { \"allow\": false },\n  \"http\": {\n    \"port\": 8765,\n    \"path\": \"/mcp\",\n    \"maxSessions\": 8,\n    \"rateLimitPerMinute\": 300,\n    \"sessionIdleTimeoutMs\": 1800000\n  },\n  \"groups\": { \"allowlist\": [\"grp_abc123\"] },\n  \"uploads\": { \"allowedRoots\": [\"C:\\\\Users\\\\you\\\\Pictures\\\\VRChat Uploads\"] },\n  \"cache\": { \"enabled\": true },\n  \"vrcx\": { \"enabled\": true }\n}\n```\n\nSee `src/config/defaults.json` for all defaults.\n\n## Local Development\n\n```bash\ngit clone https://github.com/BASIC-BIT/vrchat-mcp.git\ncd vrchat-mcp\nnpm install\nnpm run build\nnpm run check\n```\n\nUseful scripts:\n\n- `npm run dev`: run from `src/index.ts`.\n- `npm run start`: run the built server from `dist/`.\n- `npm run dev -- --transport http`: run the local Streamable HTTP server from source.\n- `npm run start -- --transport http`: run the built local Streamable HTTP server.\n- `npm run mcp:login`: start login through the local harness.\n- `npm run mcp:status`: check auth through the local harness.\n- `npm run smoke:live`: run the opt-in live smoke check.\n- `npm run generate:tools-docs`: regenerate `docs/tools.md`.\n- `npm run generate:schemas`: regenerate OpenAPI schemas.\n- `npm run mcpb:build`: build a local MCPB bundle under `mcpb/`.\n\nLive E2E tests and LLM evals are opt-in. See `docs/evals.md` for details.\n\n## License\n\nMIT. See `LICENSE`.\n",
  "bytes": 13053,
  "sha": "ff1f3ee7cc1881d3caba27c67d6e93f8a27fabfe7f5c6209c4d64d3da4013a25",
  "repo_slug": "basic-bit/vrchat-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_basic_bit_vrchat_mcp_465d41b8/readme"
}