VRChat MCP

VRChat MCP

非官方的本地 Model Context Protocol 工具，可用于管理 VRChat 好友、世界、群组、活动、通知、状态、邀请以及本地 VRCX 历史记录。

VRChat MCP 默认通过 stdio 在本地运行，也提供可选的仅限回环地址的 Streamable HTTP 模式。你的 VRChat 身份验证 Cookie 会保留在本机，默认存储在操作系统钥匙串中；如果钥匙串后端不可用，则会回退到文件存储。默认提供精选的写入工具、自动生成的读写工具，以及只读的 VRCX 本地历史记录工具；请使用 MCP 客户端或 Agent 运行环境来批准会更改账户的工具调用。

本项目为非官方项目，与 VRChat Inc. 无关联。

政策与安全边界

VRChat 不为第三方 API 应用提供公开的 OAuth 流程。VRChat 的创作者指南规定，API 应用不应请求或存储 VRChat 登录凭据、身份验证令牌或会话数据；应使用清晰的 User-Agent 标识自身；应缓存请求并在必要时降低请求频率，而不是不加限制地发送请求；也不应代表其他用户执行操作。

因此，本项目仅供用户在本地自行控制和使用。请勿将其作为托管的公共 MCP 服务运行，不要收集他人的凭据或 Cookie，不要自动发送垃圾信息或骚扰他人，也不要利用它规避 VRChat 的执法或审核。仅将写入工具用于你自己在 VRChat 中会主动执行的操作。

安装

要求：

• Node.js 24.15.0 或更高版本。
• 能运行本地 stdio 服务的 MCP 客户端。
• 已安装用于钥匙串和 VRCX SQLite 支持的原生依赖（keytar、better-sqlite3）。

在没有 libsecret 等钥匙串守护进程的无头 Linux 系统或容器中，请设置 VRCHAT_MCP_COOKIE_STORE=file，以显式启用持久化 Cookie 存储。

npm 软件包是常规安装方式：

npx -y @basicbit/vrchat-mcp

此服务也已发布到官方 MCP Registry，名称为 io.github.BASIC-BIT/vrchat-mcp。

MCP 客户端配置

大多数客户端使用以下配置格式之一。默认设置无需配置环境变量。

OpenCode

OpenCode 使用数组类型的 command 字段。

将以下内容添加到 ~/.config/opencode/opencode.json：

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

Claude Desktop、Cursor、Kiro、Roo、Windsurf

这些客户端通常将可执行文件拆分为 command 和 args。

对于要求使用 mcpServers 对象的客户端，请使用以下配置：

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

VS Code

VS Code 使用 servers 对象，而不是 mcpServers。

在 .vscode/mcp.json 中使用以下配置：

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

OpenAI Codex

将以下内容添加到 ~/.codex/config.toml 或 .codex/config.toml：

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

如果你的 Windows 客户端无法直接启动 npx，请将 cmd 用作命令，并在参数列表中填入 /c、npx、-y 和 @basicbit/vrchat-mcp。

本地 Streamable HTTP

当 MCP 客户端需要连接长时间运行的本地服务，而不是启动自己的 stdio 子进程时，请使用原生 Streamable HTTP。对于普通桌面客户端，STDIO 仍是默认且推荐的配置。

HTTP 模式：

• 仅绑定到 127.0.0.1。
• 默认使用 MCP 端点 http://127.0.0.1:8765/mcp。
• 每个 MCP 请求都必须携带 Authorization: Bearer <token>。
• 支持有状态会话、SSE 通知、资源订阅和会话终止。
• 不活动 30 分钟后清理已放弃的会话，同时保留活动的响应流。
• 所有已连接的 HTTP 客户端共用一个本地 VRChat 登录、缓存和流水线连接。
• 这不是托管模式，也不支持多用户。

生成密钥并在 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

然后将 MCP 客户端配置为使用 http://127.0.0.1:8765/mcp，并将 VRCHAT_MCP_HTTP_BEARER_TOKEN 中的令牌作为 bearer token 发送。请将令牌保存在环境变量或密钥存储中；不要将其放入 URL，也不要提交到客户端配置中。

CLI 覆盖选项：

npx -y @basicbit/vrchat-mcp --transport http --port 9000 --path /vrchat-mcp

HTTP 监听器有意禁止绑定到 LAN 或公共接口。由于 VRChat 未提供托管个人账户服务所需的 OAuth／账户隔离模型，因此不支持公共托管。

登录

将服务添加到 MCP 客户端后，请让客户端调用 vrchat_auth_begin。该工具会返回一个本地浏览器登录 URL。

登录后，调用 vrchat_auth_status 确认会话状态。默认情况下，Cookie 会存储在操作系统密钥链中，因此 MCP 服务重启后仍可保持登录状态。如果操作系统密钥链不可用，VRChat MCP 会改用文件存储。

请勿让其他人代你使用此登录流程。请勿将本地登录 URL、Cookie 或会话文件发送给托管工具或第三方服务。

实用的身份验证工具：

• vrchat_auth_begin：启动本地浏览器登录。
• vrchat_auth_status：检查服务是否已登录。
• vrchat_auth_logout：清除已存储的会话。

Bot 账号的无头登录

浏览器登录需要人工操作。VRChat 的 twoFactorAuth Cookie 有效期为 30 天，更改账号的 2FA 方式会立即撤销会话，因此无人值守部署需要有人每次重新登录。对于你拥有并使用身份验证器（TOTP）2FA 的账号，例如专用 Bot 账号，服务可以自行重新登录。

设置以下三个变量即可启用此功能。只要其中任何一个缺失或为空，行为就不会改变。

变量	用途
VRCHAT_MCP_USERNAME	VRChat 用户名或电子邮件地址。
VRCHAT_MCP_PASSWORD	VRChat 密码。
VRCHAT_MCP_TOTP_SECRET	Base32 身份验证器密钥。也接受 VRChat 以空格分组的小写形式。

当 VRChat API 请求返回 401 时，服务会使用密码和新生成的 TOTP 验证码登录一次，将新 Cookie 保存到配置的 Cookie 存储中，然后重试该请求一次。如果 VRChat 要求提供电子邮件验证码而不是 TOTP，服务不会提交验证码，而是返回常规 401 错误，并提示使用 vrchat_auth_begin。VRChat 只有在密码步骤后才会透露 2FA 方式，因此这种情况仍会计为一次失败尝试，并纳入以下退避限制。

自动登录受到速率限制，且限制状态会持久化，因此即使主机每次调用都会启动新的服务进程，限制仍然生效：

• 每 10 分钟最多进行一次自动尝试。
• 尝试失败后（密码错误、验证码被拒绝、VRChat 出错），60 分钟内不会再次自动尝试。未记录结果的尝试，例如进程在登录过程中被终止，也会计为失败。
• 冷却期间，工具错误会说明当前处于冷却状态，并给出下次允许尝试的时间。
• 记录文件为 <cookie file>.autologin.json（权限模式 0600），位于配置的 Cookie 文件路径旁。Keychain 存储使用相同路径。短暂存在的 .lock 文件可防止两个进程同时占用同一次尝试。如果无法写入记录，服务不会尝试登录。
• 使用 VRCHAT_MCP_COOKIE_STORE=memory 时不会创建文件，因此限制仅保存在内存中，只在单个进程内生效。这种方式的限制要弱得多：如果每次调用都启动一个新进程，每个进程都会登录。无头部署请使用 file 存储。

密码、TOTP 密钥、生成的验证码和 Cookie 值绝不会写入日志，也不会包含在工具结果或错误中。vrchat_auth_logout 仍会清除会话，但只要这些变量已设置，下次 API 调用时就会重新登录。

有些 MCP 主机（包括 OpenClaw）会用服务条目的 env 块替换子进程环境，而不是将其合并到自身环境中。不要将密码或 TOTP 密钥直接写入主机配置。请将它们保存在由 root 拥有且权限模式为 0600 的环境变量文件中，并让主机调用一个加载该文件后再执行服务的小型包装脚本。主机必须以有权读取该文件的用户运行包装脚本。包含 shell 元字符的值请加引号。如果主机的 env 块没有传递 PATH，请在包装脚本中设置 PATH，或使用绝对路径。

#!/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'

你可以询问的内容

示例：

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.

工具

VRChat MCP 默认提供精选工具和生成式读／写／删除路由。精选工具涵盖常见任务，输入和输出精简，便于 Agent 使用。

常见的精选工具包括：

• 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

生成式 OpenAPI API 缺口覆盖由三个路由工具提供：

• vrchat_read 用于可用的 GET 操作；传入 operationId，并在 params 下传入路径／查询／标头／Cookie 值。
• vrchat_write 用于可用的 POST/PUT/PATCH 操作；传入 operationId、params，并在 body 下传入 JSON 载荷。
• vrchat_delete 用于可用的 DELETE 操作；传入 operationId、params，并在 body 下传入可选的 JSON 载荷。

使用 vrchat_operations 列出可用的生成式操作 ID，并使用 vrchat_operation_details 查看每个操作的确切 params／body 架构。

默认启用生成式读和写工具。VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=true 会隐藏 vrchat_read。VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=true 会同时隐藏 vrchat_write 和 vrchat_delete，因为两者共用生成式写入开关。JSON 配置也可以将任一工具范围限制为指定的操作 ID；generatedWriteTools.operationIds 也涵盖 DELETE 操作，因此仅包含 POST/PUT/PATCH ID 的列表也会隐藏 vrchat_delete：

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

当 operationIds 列表为空且对应的生成式工具类别已启用时，该类别中的所有生成式操作都可通过其路由器使用，但硬性跳过的操作和已有精选替代工具的操作除外。常见工作流优先使用精选工具；生成式路由器则让本地服务能够随着 VRChat API 的演进保持可用，同时避免重复覆盖已知的精选功能，也不会暴露此客户端无法可靠调用的生成式端点。

简要指南请参阅 docs/tools-guide.md，生成式目录请参阅 docs/tools.md。

写入控制

默认启用精选写入工具和用于填补 API 缺口的生成式写入工具，以便本地 MCP 服务从首次运行起即可使用。MCP 客户端或 Agent 框架应负责控制会更改账户的操作的工具调用权限、审批和拒绝。

要强制启用只读模式，请将以下 env 片段添加到 MCP 客户端的服务条目中：

{
  "env": {
    "VRCHAT_MCP_ALLOW_WRITES": "false"
  }
}

仅当你确实要让此本地 MCP 服务执行 VRChat 账户操作时，才使用写入工具。批量社交工具设有上限，并会在遇到 429 时退避，但你仍需负责避免垃圾信息、骚扰或不受欢迎的自动化操作。

vrchat_gallery_image_upload 会将经过验证的静态 PNG 上传到已登录账户的个人图库。它只接受 imagePath；群组授权会在后续附加返回文件 ID 的群组帖子或活动工具中执行。使用前请至少配置一个绝对路径的 uploads.allowedRoots 条目。

对于群组写入工具，你可以通过 JSON 配置文件将写入范围限制为特定群组 ID：

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

然后在 MCP 客户端配置中，将 VRCHAT_MCP_CONFIG_FILE 设置为该文件的路径。

配置

配置为可选项。默认设置适用于常规本地使用。

常用环境变量：

变量	用途
VRCHAT_MCP_CONFIG_FILE	JSON 配置文件的路径。
VRCHAT_MCP_USER_AGENT	用于 VRChat API 请求的描述性 user agent。
VRCHAT_MCP_LOG_LEVEL	debug、info、warn 或 error。
VRCHAT_MCP_COOKIE_STORE	keychain、file 或 memory。默认为 keychain。
VRCHAT_MCP_COOKIE_FILE	当 VRCHAT_MCP_COOKIE_STORE=file 时的 Cookie 文件路径。
VRCHAT_MCP_USERNAME	用于无头登录的用户名。
VRCHAT_MCP_PASSWORD	用于无头登录的密码。
VRCHAT_MCP_TOTP_SECRET	用于无头登录的 Base32 TOTP 密钥。
VRCHAT_MCP_ALLOW_WRITES	设为 false 可启用只读模式。
VRCHAT_MCP_UPLOAD_ROOTS	允许本地 PNG 上传的绝对路径根目录。
VRCHAT_MCP_TRANSPORT	stdio（默认）或 http。
VRCHAT_MCP_HTTP_BEARER_TOKEN	HTTP 模式下必需的 32 个字符以上的密钥。
VRCHAT_MCP_HTTP_PORT	回环 HTTP 端口。默认为 8765。
VRCHAT_MCP_HTTP_PATH	MCP 端点路径。默认为 /mcp。
VRCHAT_MCP_HTTP_MAX_SESSIONS	最大并发 HTTP 会话数。默认为 8。
VRCHAT_MCP_HTTP_RATE_LIMIT_PER_MINUTE	每个客户端每分钟的 HTTP 请求上限。默认为 300。
VRCHAT_MCP_HTTP_SESSION_IDLE_TIMEOUT_MS	已放弃会话的超时时间。默认为 1800000。

JSON 配置示例：

{
  "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 }
}

所有默认设置请参阅 src/config/defaults.json。

本地开发

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

实用脚本：

• npm run dev：从 src/index.ts 运行。
• npm run start：从 dist/ 运行构建后的服务。
• npm run dev -- --transport http：从源代码运行本地 Streamable HTTP 服务。
• npm run start -- --transport http：运行构建后的本地 Streamable HTTP 服务。
• npm run mcp:login：通过本地运行器启动登录。
• npm run mcp:status：通过本地运行器检查身份验证状态。
• npm run smoke:live：运行可选的实时冒烟检查。
• npm run generate:tools-docs：重新生成 docs/tools.md。
• npm run generate:schemas：重新生成 OpenAPI 架构。
• npm run mcpb:build：在 mcpb/ 下构建本地 MCPB 包。

实时 E2E 测试和大模型评估均为可选。详情请参阅 docs/evals.md。

许可证

MIT。请参阅 LICENSE。