# Vrchat Mcp

> MCP server for VRChat friends, worlds, groups, events, notifications, and VRCX history.

- **Type:** MCP server
- **Install:** `agentstack add mcp-basic-bit-vrchat-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BASIC-BIT](https://agentstack.voostack.com/s/basic-bit)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.2
- **License:** MIT
- **Upstream author:** [BASIC-BIT](https://github.com/BASIC-BIT)
- **Source:** https://github.com/BASIC-BIT/vrchat-mcp
- **Website:** https://github.com/BASIC-BIT/vrchat-mcp#readme

## Install

```sh
agentstack add mcp-basic-bit-vrchat-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# VRChat MCP

Unofficial local [Model Context Protocol](https://modelcontextprotocol.io/) tools for VRChat friends, worlds, groups, events, notifications, status, invites, and local VRCX history.

[](https://www.npmjs.com/package/@basicbit/vrchat-mcp) [](./LICENSE)

VRChat MCP runs locally through stdio. 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:

```bash
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`:

```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:

```json
{
  "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`:

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

### OpenAI Codex

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

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

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

## What You Can Ask

Examples:

```txt
Show my VRChat status and current location.
```

```txt
Which friends are online, grouped by world?
```

```txt
Search my friends for Alice and show their profile.
```

```txt
Find public VRChat events happening today.
```

```txt
Invite Bob to my current instance.
```

```txt
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_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:

- `vrchat_read` for available GET operations; pass `operationId` plus path/query/header/cookie values under `params`.
- `vrchat_write` for available POST/PUT/PATCH operations; pass `operationId`, `params`, and JSON payloads under `body`.
- `vrchat_delete` for available DELETE operations; pass `operationId`, `params`, and optional JSON payloads under `body`.

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. Set `VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=true` or `VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=true` to hide them, or use JSON config to narrow either surface to specific operation IDs:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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_ALLOW_WRITES` | Set to `false` for read-only mode.                       |

Example JSON config:

```json
{
  "auth": { "cookieStore": "file" },
  "writes": { "allow": false },
  "groups": { "allowlist": ["grp_abc123"] },
  "cache": { "enabled": true },
  "vrcx": { "enabled": true }
}
```

See `src/config/defaults.json` for all defaults.

## Local Development

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

Useful scripts:

- `npm run dev`: run from `src/index.ts`.
- `npm run start`: run the built server from `dist/`.
- `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`: regenerate `docs/tools.md`.
- `npm run generate:schemas`: regenerate OpenAPI schemas.
- `npm run mcpb:build`: build a local MCPB bundle under `mcpb/`.

Live E2E tests and LLM evals are opt-in. See `docs/evals.md` for details.

## License

MIT. See `LICENSE`.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BASIC-BIT](https://github.com/BASIC-BIT)
- **Source:** [BASIC-BIT/vrchat-mcp](https://github.com/BASIC-BIT/vrchat-mcp)
- **License:** MIT
- **Homepage:** https://github.com/BASIC-BIT/vrchat-mcp#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.2 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.2** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-basic-bit-vrchat-mcp
- Seller: https://agentstack.voostack.com/s/basic-bit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.