Allows an AI client to interact with VRChat data including friends, worlds, groups, events, notifications, and local VRCX history.
Also known as BASIC-BIT/vrchat-mcp, vrchat-mcp, @basicbit/vrchat-mcp
- Stars
- 3
- Tools
- 15
- Downloads, 30 days
- 793
- Latest version
- 0.1.15
- Last commit
- Nov 9, 2026
- License
- MIT
What is VRChat MCP?
VRChat allows an AI client to interact with VRChat data including friends, worlds, groups, events, notifications, and local VRCX history. It exposes 15 tools, such as vrchat_me, vrchat_friends_overview, vrchat_friends_search.
Summary generated from the project's README
About VRChat MCP server
VRChat MCP provides a local interface for AI clients to interact with VRChat data. It allows users to manage friends, search for worlds, view group profiles, check upcoming events, and access recent notifications. The server also integrates with local VRCX history to retrieve recent instance data. It is designed as a personal tool for local use via stdio or an optional loopback-only Streamable HTTP mode.
Users can perform actions using curated tools like vrchat_invite or vrchat_friend_request, or use generated routers for broader API coverage. Authentication is handled locally, with cookies stored in the OS keychain or a local file. For headless bot accounts, the server supports automatic login using a username, password, and TOTP secret. This setup ensures that sensitive credentials remain on the user's machine rather than being sent to a hosted service.
What you can do with it
- 1Manage social interactionsAsk the AI to find specific friends and send them an invitation to your current instance.
- 2Discover VRChat contentRequest a list of public events that are scheduled to happen today.
- 3Analyze local activityRetrieve a list of worlds you have recently visited using your local VRCX history.
- 4Monitor social statusCheck which of your friends are currently online and which worlds they are in.
Written from the project's README. Every use case is checked against a quote from it.
How to install VRChat MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall VRChat MCP in Claude Code
$ claude mcp add vrchat-mcp -- npx -y @basicbit/vrchat-mcpInstall VRChat MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"vrchat-mcp": {
"command": "npx",
"args": [
"-y",
"@basicbit/vrchat-mcp"
]
}
}
}Install VRChat MCP in VS Code
.vscode/mcp.json
{
"servers": {
"vrchat-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@basicbit/vrchat-mcp"
]
}
}
}Install VRChat MCP in VS Code CLI
$ code --add-mcp '{"name":"vrchat-mcp","type":"stdio","command":"npx","args":["-y","@basicbit/vrchat-mcp"]}'Install VRChat MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"vrchat-mcp": {
"command": "npx",
"args": [
"-y",
"@basicbit/vrchat-mcp"
]
}
}
}Install VRChat MCP in Codex
$ codex mcp add vrchat-mcp -- npx -y @basicbit/vrchat-mcpInstall VRChat MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.vrchat-mcp] command = "npx" args = ["-y", "@basicbit/vrchat-mcp"]
Install VRChat MCP in Gemini CLI
$ gemini mcp add -s user vrchat-mcp npx -- -y @basicbit/vrchat-mcpInstall VRChat MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"vrchat-mcp": {
"command": "npx",
"args": [
"-y",
"@basicbit/vrchat-mcp"
]
}
}
}VRChat MCP tools 15
Detected from the READMEvrchat_mevrchat_friends_overviewvrchat_friends_searchvrchat_friend_detailsvrchat_worlds_searchvrchat_group_profilevrchat_events_upcomingvrchat_notifications_recentvrchat_instance_link_eventvrchat_gallery_image_uploadvrchat_invitevrchat_group_invite
| 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 | — |
Show all 15 toolsShow fewer tools
vrchat_friend_requestvrchat_boopvrcx_instances_recent
| vrchat_friend_request | — | |
| vrchat_boop | — | |
| vrcx_instances_recent | — |
Configuration
VRCHAT_MCP_ALLOW_WRITESAllow non-GET VRChat API write operations. Defaults to true for local full-capability use; set to false for read-only mode.
VRCHAT_MCP_CONFIG_FILEPath to a JSON config file for settings not supplied through environment variables.
VRCHAT_MCP_COOKIE_FILECookie file path used when VRCHAT_MCP_COOKIE_STORE is file.
VRCHAT_MCP_COOKIE_STORECookie storage backend for VRChat authentication. The keychain mode falls back to file storage if the OS keychain is unavailable.
VRCHAT_MCP_LOG_LEVELLog level for stderr diagnostics.
VRCHAT_MCP_PASSWORDVRCHAT_MCP_TOTP_SECRETVRCHAT_MCP_UPLOAD_ROOTSAbsolute directories from which local PNG uploads may be read. Separate multiple roots with the platform path delimiter.
VRCHAT_MCP_USERNAMEVRCHAT_MCP_USER_AGENTDescriptive User-Agent for VRChat API requests.
| Name | Description | |
|---|---|---|
| VRCHAT_MCP_ALLOW_WRITES | Allow non-GET VRChat API write operations. Defaults to true for local full-capability use; set to false for read-only mode. | |
| VRCHAT_MCP_CONFIG_FILE | Path to a JSON config file for settings not supplied through environment variables. | |
| VRCHAT_MCP_COOKIE_FILE | Cookie file path used when VRCHAT_MCP_COOKIE_STORE is file. | |
| VRCHAT_MCP_COOKIE_STORE | Cookie storage backend for VRChat authentication. The keychain mode falls back to file storage if the OS keychain is unavailable. | |
| VRCHAT_MCP_LOG_LEVEL | Log level for stderr diagnostics. | |
| VRCHAT_MCP_PASSWORD | — | |
| VRCHAT_MCP_TOTP_SECRET | — | |
| VRCHAT_MCP_UPLOAD_ROOTS | Absolute directories from which local PNG uploads may be read. Separate multiple roots with the platform path delimiter. | |
| VRCHAT_MCP_USERNAME | — | |
| VRCHAT_MCP_USER_AGENT | Descriptive User-Agent for VRChat API requests. |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubVRChat 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 VRCHAT_MCP_COOKIE_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.BITRATE-Labs/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:
- Binds only to
127.0.0.1. - Uses the MCP endpoint
http://127.0.0.1:8765/mcpby default. - Requires
Authorization: Bearer <token>on every MCP request. - Supports stateful sessions, SSE notifications, resource subscriptions, and session termination.
- Reaps abandoned sessions after 30 minutes of inactivity while preserving active response streams.
- Shares one local VRChat login, cache, and pipeline connection across all connected HTTP clients.
- Is not a hosted or multi-user mode.
Generate a secret and launch the server in 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
Then 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.
CLI overrides:
npx -y @basicbit/vrchat-mcp --transport http --port 9000 --path /vrchat-mcp
The 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.
Login
After adding the server to your MCP client, ask it to call vrchat_auth_begin. The tool returns a local browser login URL.
After 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.
Do 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.
Useful auth tools:
vrchat_auth_begin: start local browser login.vrchat_auth_status: check whether the server is logged in.vrchat_auth_logout: clear the stored session.
Headless Login for Bot Accounts
Browser login needs a person. VRChat's twoFactorAuth cookie lasts 30 days, and changing an account's 2FA method revokes its session immediately, so an unattended deployment would otherwise need someone to log in again each time. For an account you own and operate with authenticator (TOTP) 2FA, such as a dedicated bot account, the server can log itself back in.
Set all three variables to turn it on. If any of them is missing or empty, nothing changes.
| Variable | Use |
|---|---|
VRCHAT_MCP_USERNAME |
VRChat username or email. |
VRCHAT_MCP_PASSWORD |
VRChat password. |
VRCHAT_MCP_TOTP_SECRET |
Base32 authenticator secret. VRChat's space-grouped lowercase form is accepted too. |
When a VRChat API request returns 401, the server logs in once with the password and a freshly generated TOTP code, saves the new cookies to the configured cookie store, and retries the request once. If VRChat asks for an email code instead of TOTP, the server submits no code and returns the normal 401 error with a note to use vrchat_auth_begin. VRChat only reveals the 2FA method after the password step, so that still counts as a failed attempt for the backoff below.
Automatic logins are rate limited, and the limit is persisted so it holds when the host spawns a fresh server process for every call:
- At most one automatic attempt every 10 minutes.
- After a failed attempt (wrong password, rejected code, VRChat error) no automatic attempt for 60 minutes. An attempt that never recorded an outcome, for example because the process was killed mid-login, counts as failed.
- While in cooldown, the tool error says so and gives the time of the next allowed attempt.
- The record is
<cookie file>.autologin.json(mode 0600), beside the configured cookie file path. Keychain storage uses the same path. A short-lived.lockfile stops two processes from claiming the same attempt. If the record cannot be written, the server does not try to log in. - With
VRCHAT_MCP_COOKIE_STORE=memorythere is no file, so the limit lives in memory and only applies within one process. That is much weaker: with a process per call, every process would log in. Usefilestorage for headless deployments.
The password, TOTP secret, generated codes, and cookie values are never logged or included in tool results or errors. vrchat_auth_logout still clears the session, but while the variables are set the next API call logs back in.
Some MCP hosts, OpenClaw included, replace the child environment with the server entry's env block instead of merging it into their own. Do not put the password or TOTP secret inline in the host config. Keep them in a root-owned env file with mode 0600 and point the host at a small wrapper script that loads the file and execs the server. The host must run the wrapper as a user that can read the file. Quote values that contain shell metacharacters. If the host's env block does not pass PATH, set it in the wrapper or use absolute paths.
#!/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'
What You Can Ask
Examples:
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.
Tools
VRChat MCP exposes curated tools plus generated read/write/delete routers by default. Curated tools cover common tasks with compact, agent-friendly inputs and outputs.
Common curated tools include:
vrchat_mevrchat_friends_overviewvrchat_friends_searchvrchat_friend_detailsvrchat_worlds_searchvrchat_group_profilevrchat_events_upcomingvrchat_notifications_recentvrchat_instance_link_eventvrchat_gallery_image_uploadvrchat_invitevrchat_group_invitevrchat_friend_requestvrchat_boopvrcx_instances_recent
Generated OpenAPI API-gap coverage uses three router tools:
vrchat_readfor available GET operations; passoperationIdplus path/query/header/cookie values underparams.vrchat_writefor available POST/PUT/PATCH operations; passoperationId,params, and JSON payloads underbody.vrchat_deletefor available DELETE operations; passoperationId,params, and optional JSON payloads underbody.
Use vrchat_operations to list available generated operation IDs and vrchat_operation_details for exact per-operation params/body schemas.
Generated 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:
{
"generatedReadTools": { "enabled": true, "operationIds": ["getAvatarStyles"] },
"generatedWriteTools": { "enabled": true, "operationIds": ["selectAvatar"] }
}
When 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.
See docs/tools-guide.md for a short guide and docs/tools.md for the generated catalog.
Write Controls
Curated 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.
To force read-only mode, add this env fragment inside the server entry for your MCP client:
{
"env": {
"VRCHAT_MCP_ALLOW_WRITES": "false"
}
}
Only 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.
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.
For group write tools, you can restrict writes to specific group IDs with a JSON config file:
{
"groups": {
"allowlist": ["grp_abc123"]
}
}
Then set VRCHAT_MCP_CONFIG_FILE to that file path in your MCP client config.
Configuration
Configuration is optional. Defaults cover normal local use.
Common environment variables:
| Variable | Use |
|---|---|
VRCHAT_MCP_CONFIG_FILE |
Path to a JSON config file. |
VRCHAT_MCP_USER_AGENT |
Descriptive user agent for VRChat API requests. |
VRCHAT_MCP_LOG_LEVEL |
debug, info, warn, or error. |
VRCHAT_MCP_COOKIE_STORE |
keychain, file, or memory. Defaults to keychain. |
VRCHAT_MCP_COOKIE_FILE |
Cookie file path when VRCHAT_MCP_COOKIE_STORE=file. |
VRCHAT_MCP_USERNAME |
Username for headless login. |
VRCHAT_MCP_PASSWORD |
Password for headless login. |
VRCHAT_MCP_TOTP_SECRET |
Base32 TOTP secret for headless login. |
VRCHAT_MCP_ALLOW_WRITES |
Set to false for read-only mode. |
VRCHAT_MCP_UPLOAD_ROOTS |
Absolute roots allowed for local PNG uploads. |
VRCHAT_MCP_TRANSPORT |
stdio (default) or http. |
VRCHAT_MCP_HTTP_BEARER_TOKEN |
Required 32+ character secret for HTTP mode. |
VRCHAT_MCP_HTTP_PORT |
Loopback HTTP port. Defaults to 8765. |
VRCHAT_MCP_HTTP_PATH |
MCP endpoint path. Defaults to /mcp. |
VRCHAT_MCP_HTTP_MAX_SESSIONS |
Maximum concurrent HTTP sessions. Defaults to 8. |
VRCHAT_MCP_HTTP_RATE_LIMIT_PER_MINUTE |
Per-client HTTP request limit. Defaults to 300. |
VRCHAT_MCP_HTTP_SESSION_IDLE_TIMEOUT_MS |
Abandoned-session timeout. Defaults to 1800000. |
Example JSON config:
{
"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 }
}
See src/config/defaults.json for all defaults.
Local Development
git clone https://github.com/BITRATE-Labs/vrchat-mcp.git
cd vrchat-mcp
npm install
npm run build
npm run check
Useful scripts:
npm run dev: run fromsrc/index.ts.npm run start: run the built server fromdist/.npm run dev -- --transport http: run the local Streamable HTTP server from source.npm run start -- --transport http: run the built local Streamable HTTP server.npm run mcp:login: start login through the local harness.npm run mcp:status: check auth through the local harness.npm run smoke:live: run the opt-in live smoke check.npm run generate:tools-docs: regeneratedocs/tools.md.npm run generate:schemas: regenerate OpenAPI schemas.npm run mcpb:build: build a local MCPB bundle undermcpb/.
Live E2E tests and LLM evals are opt-in. See docs/evals.md for details.
License
MIT. See LICENSE.
VRChat MCP questions
How do I add VRChat MCP to Claude Code?
Run claude mcp add vrchat-mcp -- npx -y @basicbit/vrchat-mcp in your terminal. Add --scope user to make it available in every project.
How do I add VRChat MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does VRChat MCP provide?
It exposes 15 tools, including vrchat_me, vrchat_friends_overview, vrchat_friends_search, vrchat_friend_details, vrchat_worlds_search.
How do I log in to VRChat using this server?
Ask your MCP client to call the vrchat_auth_begin tool, which will return a local browser login URL for you to complete the process.
Can I use this server for a headless bot account?
Yes, by setting the VRCHAT_MCP_USERNAME, VRCHAT_MCP_PASSWORD, and VRCHAT_MCP_TOTP_SECRET environment variables, the server can automatically log itself back in using TOTP.
Where are my VRChat login cookies stored?
By default, cookies are stored in your OS keychain, falling back to file storage if a keychain backend is unavailable.
Is it possible to connect via HTTP instead of stdio?
Yes, the server offers an opt-in loopback-only Streamable HTTP mode that binds to 127.0.0.1.