VRChat MCP

Unofficial localModel Context Protocoltools for VRChat friends, worlds, groups, events, notifications, status, invites, and local VRCX history.

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

Claude Desktop, Cursor, Kiro, Roo, Windsurf

These clients usually split the executable intocommandplusargs.

Use this in clients that expect anmcpServersobject:

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

VS Code uses aserversobject instead ofmcpServers.

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

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

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

If your Windows client cannot spawnnpxdirectly, usecmdas the command and put/c,npx,-y, and@basicbit/vrchat-mcpin the argument list.

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.

- Binds only to127.0.0.1.
- Uses the MCP endpointhttp://127.0.0.1:8765/mcpby default.
- RequiresAuthorization: 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 usehttp://127.0.0.1:8765/mcpand send the token fromVRCHAT_MCP_HTTP_BEARER_TOKENas 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.

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.

After adding the server to your MCP client, ask it to callvrchat_auth_begin. The tool returns a local browser login URL.

- vrchat_auth_begin: start local browser login.
- vrchat_auth_status: check whether the server is logged in.
- vrchat_auth_logout: clear the stored session.

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.

Show recent worlds from my local VRCX history.

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.

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

Generated OpenAPI API-gap coverage uses three router tools:

Usevrchat_operationsto list available generated operation IDs andvrchat_operation_detailsfor exact per-operation params/body schemas.

Generated read and write tools are enabled by default.VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=truehidesvrchat_read.VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=truehides bothvrchat_writeandvrchat_delete, which share the generated-write switch. JSON config can also narrow either surface to specific operation IDs;generatedWriteTools.operationIdscovers DELETE operations too, so a list holding only POST/PUT/PATCH IDs also hidesvrchat_delete:

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

When anoperationIdslist 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.

Seedocs/tools-guide.mdfor a short guide anddocs/tools.mdfor the generated catalog.

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 thisenvfragment 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.

For group write tools, you can restrict writes to specific group IDs with a JSON config file:

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

Then setVRCHAT_MCP_CONFIG_FILEto that file path in your MCP client config.

Configuration is optional. Defaults cover normal local use.

Seesrc/config/defaults.jsonfor all defaults.

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

- 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. Seedocs/evals.mdfor details.

Fetches daily Wordle solutions using the official Wordle API.

Live AI agent city-economy on Base L2 — 92 NPC agents earn real USDC via jobs, trading, and businesses across 10 cities. Claim jobs for USDC payouts, chat with agents, check AGWC token data, and get live crypto news. 11 tools, no API key.

Comprehensive astrology MCP backed by the AstroWay Calculation API — natal, synastry, transits, Vedic dashas (Vimshottari/Yogini/Ashtottari/Kalachakra), Tarot (Rider-Waite-Smith / Marseille / Lenormand), Numerology, Human Design, AI horoscopes. Sub-arcsecond Swiss Ephemeris precision. 10 000 free credits/month, no card required. Install: npx @astroway/mcp

40 MCP tools for AI agents to play a yield-generating pet game on Base chain. Earn USDC/ETH/BTC by raising virtual pets. Impact: every action burns tokens and retires carbon credits.

An MCP server for accessing Bazi (Chinese astrology) data, requiring an API key.

Connect to UCI-compatible chess engines like Stockfish to play and analyze games. Requires a local chess engine binary.

Connects Large Language Models (LLMs) with Guild Wars 2 data sources. Requires a Guild Wars 2 API key for wallet functionality.

An MCP server for '海龟汤' (Turtle Soup), a scenario-based reasoning puzzle game.

Play a legendary text adventure by talking to your AI — no commands to memorize. The Hidden Empire puts a full underground world of puzzles, treasures, and trolls inside your conversation. Speak naturally: say 'head north,' 'grab the lantern,' or 'what am I carrying?' and your AI handles the rest. Execute multi-move plans in one shot, undo mistakes instantly, and save up to 20 named playthroughs you can resume from any session. Based on the MIT-licensed Zork I source, rebuilt from the ground up for AI-native play.

Provides daily horoscope readings and fortune telling for all 12 zodiac signs using a horoscope API.