# VRChat MCP server

> Allows an AI client to interact with VRChat data including friends, worlds, groups, events, notifications, and local VRCX history.

- Repository: https://github.com/BASIC-BIT/vrchat-mcp
- Page: https://hostedmcp.org/servers/basic-bit/vrchat-mcp
- Transport: stdio
- Stars: 3
- License: MIT
- Latest version: 0.1.15

## Install

### Claude Code

```sh
claude mcp add vrchat-mcp -- npx -y @basicbit/vrchat-mcp
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

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

### VS Code CLI

```sh
code --add-mcp '{"name":"vrchat-mcp","type":"stdio","command":"npx","args":["-y","@basicbit/vrchat-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add vrchat-mcp -- npx -y @basicbit/vrchat-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

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

### Gemini CLI

```sh
gemini mcp add -s user vrchat-mcp npx -- -y @basicbit/vrchat-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `VRCHAT_MCP_ALLOW_WRITES` | no | no | 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` | no | no | Path to a JSON config file for settings not supplied through environment variables. |
| `VRCHAT_MCP_COOKIE_FILE` | no | no | Cookie file path used when VRCHAT_MCP_COOKIE_STORE is file. |
| `VRCHAT_MCP_COOKIE_STORE` | no | no | Cookie storage backend for VRChat authentication. The keychain mode falls back to file storage if the OS keychain is unavailable. |
| `VRCHAT_MCP_LOG_LEVEL` | no | no | Log level for stderr diagnostics. |
| `VRCHAT_MCP_PASSWORD` | no | no |  |
| `VRCHAT_MCP_TOTP_SECRET` | no | no |  |
| `VRCHAT_MCP_UPLOAD_ROOTS` | no | no | Absolute directories from which local PNG uploads may be read. Separate multiple roots with the platform path delimiter. |
| `VRCHAT_MCP_USERNAME` | no | no |  |
| `VRCHAT_MCP_USER_AGENT` | no | no | Descriptive User-Agent for VRChat API requests. |

## Tools (15)

- `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`
- `vrchat_friend_request`
- `vrchat_boop`
- `vrcx_instances_recent`

## FAQ

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