vrchat-mcp

一个用于 VRChat API 的 MCP 服务器。OpenAPI 规范中的全部 297 个操作在构建时生成，另有手写工具处理单个端点无法完成的事情：两步登录、文件上传、查看图片和事件管道。

通过 stdio 在本地运行，作为 Claude Code 或 Claude Desktop 的子进程。默认只读，除非你另行授权。

基于 Bun、官方 MCP TypeScript SDK v2 以及官方 vrchat JavaScript SDK 构建。工具来自 VRChat OpenAPI specification 并已提交，因此工具面会紧跟上游，而不是逐渐与上游脱节。

速查表

bun install && bun link                # `vrchat-mcp` is now on PATH
cp .env.example .env                   # fill in username, password, contact
claude mcp add vrchat -- vrchat-mcp

最简 .env：

VRCHAT_USERNAME=you
VRCHAT_PASSWORD=hunter2
VRCHAT_CONTACT=you@your-domain.tld     # must be real, VRChat 403s generic agents

工具名称带有来源标识。双下划线表示从规范生成（vrchat__getCurrentUser），因此该名称可以在 VRChat 自己的文档中搜索到。单下划线表示此服务器手写（vrchat_authStatus）。

以下为全部手写工具：

最后四个仅在 VRCHAT_MCP_WEBSOCKET=1 时出现。

Related MCP server: Portals MCP

安装

bun link 会将 vrchat-mcp 可执行文件放到你的 PATH 中，这样下游任何东西都不需要知道代码检出在哪里。

bun install
bun link          # from the repo root

按名称注册：

claude mcp add vrchat -- vrchat-mcp

或者在 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "vrchat": {
      "command": "vrchat-mcp"
    }
  }
}

这就是全部配置。凭据来自仓库的 .env，因此不必在此重复，不过你在 env 块中放入的任何内容都会优先生效。使用 bun unlink 移除该命令。

如果你不希望把任何内容放到 PATH 中，可以用绝对路径指向入口文件。服务器是从任意工作目录启动的，所以相对路径行不通。

claude mcp add vrchat -- bun run /abs/path/to/vrchat-mcp/src/index.ts

联系方式要求

VRChat 会以 403 拒绝通用 User-Agent。VRCHAT_CONTACT 会进入 SDK 在每次请求（API 和 WebSocket 同样）中发送的描述性 User-Agent，而且它实际上是强制性的。

该值必须是真实的。SDK 会拒绝任何包含 @example.com 的联系信息，所以那个显而易见的占位符恰好是保证失败的值。服务器会在第一次工具调用时将其报告为配置错误，而不是让它以神秘的 403 出现。

配置

三层配置，最高优先级在前。项目可以设置自己的选项，而无需重复你的凭据。

1. 真实环境变量，包括 MCP 客户端的 env 块

2. 命令运行所在目录中的 .env，由 Bun 自动加载

3. 仓库根目录下的 .env

因此，一个只想使用商店工具、并且使用你已经配置好的凭据的项目，只需要在旁边写一行：

# ~/my-project/.env
VRCHAT_MCP_TAGS=store

布尔值接受 1 或 true，不区分大小写。

状态存储位置

状态按项目隔离。在项目内运行服务器，其会话和事件历史就存放在该项目的 .vrchat-mcp/ 中。项目根目录是通过从工作目录向上查找 .git、package.json、deno.json、pyproject.toml 或 go.mod 来确定的，因此从子目录启动也能访问同一份状态，而不会在下一级留下一个孤立的第二个会话。

该目录会自动对版本控制隐藏：vrchat-mcp 在创建时会在其中写入一个包含 * 的 .gitignore，因此会话文件（一种认证凭据）得到保护，而宿主项目无需为此添加规则。

因此每个项目会分别登录，新项目中的第一次调用可能会要求输入 2FA 验证码。若想在所有地方共享同一个登录，就让每次安装指向同一个文件：

VRCHAT_MCP_SESSION=/abs/path/to/shared/session.json

安全闸门

服务器以只读模式启动。297 个操作中默认注册 150 个。任何写入、删除、消费或审核的操作都不会出现，除非你主动要求。

破坏性操作和资金操作叠加在写操作之上，因此启用写操作只会授予创建和编辑的能力，绝不会授予删除或消费的能力。管理员操作是独立的，不会被任何其他设置隐含：允许代理编辑你自己的内容绝不应该同时允许它删除账户。

你所选择启用的是：

• ALLOW_WRITES 允许代理创建和更改你拥有的内容。可逆，大多可手动完成。

• ALLOW_DESTRUCTIVE_WRITES 增加了无法撤销的调用。删除、封禁、踢出、关闭实例、清除用户持久化数据。

• ALLOW_PURCHASES 允许代理消费真实余额。purchaseProductListing 是一笔实时交易。不要因为某个工具列表看起来不完整就设置它。

• ALLOW_ADMIN 暴露了 deleteUser 等操作。其中大多数在普通账户上会返回 403，但 deleteUser 绝不能成为意外。

受限制的操作无论怎样都会保留在生成的表中，因此覆盖范围与规范保持 1:1，而且黑名单可以在 diff 中审查。MCP 注解（readOnlyHint、destructiveHint）也已设置，因此那些会展示这些注解的客户端可以给出提示。

我缺少哪些工具？

门控工具直接不存在，读起来就像"VRChat 做不到这件事"，而不是"这个服务器被告知不要做"。这个错误在现实中已经犯过：一个代理报告说经济 API 是只读的，而实际上写工具是存在的，只是被一个标志位挡住了。

vrchat_authStatus 填补了这个空白。它报告每个标签和安全级别、每个级别包含多少个操作、当前暴露了多少个，以及需要修改哪个确切的 .env 才能暴露其余部分。

{
  "availability": {
    "toolsRegistered": 12,
    "toolsHidden": 285,
    "tagFilter": ["store"],
    "kinds": { "write": { "enabled": false, "hidden": 88 } },
    "nextSteps": [
      "88 `write` operations are hidden. Ask the user to set VRCHAT_MCP_ALLOW_WRITES=1 ..."
    ]
  }
}

在断定某个功能不受支持之前，先调用它。

选择要暴露哪些工具

VRCHAT_MCP_TAGS 选择标签。未设置时注册所有内容，而 everything 会明确说明这一点，这比从 JSON 配置中删除键更容易。all 和 * 也可以。

VRCHAT_MCP_TAGS=everything          # all 297 operations
VRCHAT_MCP_TAGS=store               # just the storefront, 19 operations
VRCHAT_MCP_TAGS=store,users,worlds  # matches any of the three

规范标签：authentication、avatars、calendar、economy、favorites、files、friends、groups、instances、inventory、invite、jams、miscellaneous、notifications、playermoderation、prints、props、users、worlds。另外还有 store，这是此服务器额外添加的。

如果某个标签没有匹配到任何内容，启动时会在 stderr 上发出警告，并由 vrchat_authStatus 报告。否则，像 stores 这样的拼写错误不会注册任何生成的工具，看起来就像服务器坏了。

登录

登录是惰性的。启动时不进行任何身份验证，因此 tools/list 在没有任何凭据的情况下也能工作，服务器保持可检查状态。第一次需要会话的工具调用才会触发登录。

设置了 VRCHAT_TOTP_SECRET 后，事情就到此为止了。永远不会出现提示。

没有它，VRChat 会发送一封包含验证码的邮件，调用会返回"parked"状态而不是挂起：

vrchat__getCurrentUser
  -> Login paused: VRChat emailed a code. Ask the user for it, call
     vrchat_submitTwoFactorCode { requestId: 'a1b2c3d4', code: '……' },
     then retry the original call.

用 vrchat_submitTwoFactorCode 回答它，然后重试。会话会持久化，所以每个项目只发生一次，直到过期。

从新网络登录

更换代理、VPN 或 ISP 会触发一个不是双重验证码的检查，而这两者看起来非常相似，足以浪费大量时间。VRChat 会返回以下其中一种：

401  It looks like you're logging in from somewhere new! Check your email for a message from VRChat.
429  Logging in from too many places? Check your email for verification link

两者意思相同，但都不是表面看起来的那样。邮件中包含的是一个链接，而不是六位数的代码，所以 vrchat_submitTwoFactorCode 帮不上忙。登录需要两轮：

1. 工具调用失败并显示其中一条消息

2. 用户打开邮件中的链接

3. 调用 vrchat_retryLogin。VRChat 只在第二次尝试时发送真正的代码

4. 用户读出代码，调用 vrchat_submitTwoFactorCode

5. 重试原始工具

429 是伪装成限流状态的认证挑战，所以本地限流器会忽略它。等待不会清除它，而且每次额外尝试都会消耗该账户有限的会话槽位之一，这正是首先产生 429 的原因。失败的登录会被缓存 30 秒，这样突发的工具调用不会变成突发的登录尝试。vrchat_retryLogin 会清除该缓存，因为到那时用户已经完成了失败所等待的事情。

登录期间的并行调用

代理会同时发出大量工具调用，在冷启动时它们都会落在一个未认证的客户端上。一个调用驱动登录。其他调用最多等待三秒，然后返回 login_pending 而不是阻塞，因此缓慢的登录只会拖住一个工具调用而不是所有工具调用，而停在代码上的登录只会弹出一个提示而不是多个。

_responseKeys

每个工具都接受 _responseKeys，并且默认情况下每个工具都返回原始的上游负载。没有服务器端的管理，因为手工挑选的字段列表是在猜测什么重要，对于需要其他字段的人来说是错误的，而且必须针对不断变化的规范维护 297 个操作。代理知道它这次调用想要什么。它应该说出来。

一个 World 对象大约 4 KB。缩小通常可以将其减少一半以上。

投影保持形状。对象保持嵌套，数组保持顺序和长度，因此在一次调用中学到的路径在下次调用中仍然有效。

发现比投影更重要。代理不能要求它不知道存在的键，而静默的空结果会使这种设计比裁剪更糟糕。因此，不匹配的路径会以 _unmatched 的形式返回，同时还有 _availableKeys 列出实际存在的内容。数组元素键的命名形式为 *.id、*.name，这种形式可以作为 _responseKeys 条目使用。

["*"] 按引用返回输入，因此原始路径被证明是无损的，并且永远不会隐藏任何内容。

查看图片

vrchat_getImage 下载 VRChat 图片并将其作为图片块返回，这样模型就可以查看它，而不是报告一个 URL。

{ "name": "vrchat_getImage",
  "arguments": { "url": "https://api.vrchat.cloud/api/1/file/file_.../1/256" } }

传入来自用户、世界、头像、打印、产品或商品中的任何 imageUrl 或 thumbnailImageUrl，或者传入 fileId 让工具构建 URL。savePath 也会将字节写入磁盘。

如果存在以 /256 或 /512 结尾的 URL，请优先使用。图片以 base64 形式传输，因此全尺寸纹理需要消耗大量上下文，却不会带来额外的细节。超过 4 MB 的内容将被拒绝；如果你确实需要，可以提高 maxBytes。

该工具只获取 VRChat 托管的图片，而且只有 api.vrchat.cloud 会收到你的会话 cookie。一个在持有会话的情况下获取调用者提供的 URL 的工具，除非受到限制，否则就是一个请求伪造原语，而发送给 CDN 的 cookie 就是送出的 cookie。

上传文件

传入本地文件路径。服务器在你的机器上运行并自行读取文件，因此文件内容永远不会进入对话。将 2 MB 的 PNG 内联为 base64 将花费大约 2.7 MB 的工具参数，比调用中所有其他内容的总和还要多。

当磁盘上没有文件时，例如代理刚刚生成的图片，同样的参数会以内联方式接收字节：

{ "file": { "data": "iVBORw0KGgo...", "mimeType": "image/png", "filename": "icon.png" } }

data: URI 也可以用在字符串位置，所以 "file": "data:image/png;base64,iVBORw0..." 是等价的。filename 是可选的，省略时会根据 MIME 类型自动生成，因为 VRChat 会拒绝无法命名的上传。只要存在路径就优先使用路径：内联每字节文件大约需要 1.33 字节的工具参数，而且这与其他所有内容来自同一个上下文预算。

有八个操作直接接收文件，每次调用一个：

{ "name": "vrchat__uploadImage",
  "arguments": { "file": "C:/Users/me/Pictures/icon.png", "tag": "icon" } }

结果会指明发送了哪些字节，以及它们以何种形式到达，这是区分成功上传正确文件和成功上传错误文件的唯一方法：

{ "uploaded": [
    { "field": "file", "name": "icon.png", "bytes": 48211, "type": "image/png", "source": "path" }
  ],
  "result": { "id": "file_...", "name": "icon.png" } }

对于其他所有情况，vrchat_uploadFile 运行 VRChat 的四步序列（创建记录、请求预签名 URL、传输字节、完成）并返回完成的文件记录。将其用于资源包和 unity 包。字节通过普通请求直接发送到 VRChat 的存储提供商，故意不通过 API 客户端，因为该客户端会将其发送的所有内容都附加你的会话 cookie，而存储主机是第三方。

上传是写操作，所以所有这些都需要 VRCHAT_MCP_ALLOW_WRITES=1。文件上限为 100 MB，空文件在到达 VRChat 之前就会被拒绝，否则 VRChat 会存储一条损坏的记录。如果 vrchat_uploadFile 中途失败，它会指明它创建的文件记录，这样你就可以用 vrchat__getFile 检查它，并用 vrchat__deleteFile 删除它。

运营商店

管理店面是普通的写操作，而不是 money 操作。创建商品、重命名、更改其图片、发布或取消发布列表：这些都不会花费或赚取任何东西，因此只需要 VRCHAT_MCP_ALLOW_WRITES=1。money 门控用于购买和支付处理器。

VRCHAT_MCP_TAGS=store
VRCHAT_MCP_ALLOW_WRITES=1

设置商品图片只需一次调用：

{ "name": "vrchat_setProductImage",
  "arguments": { "productId": "prod_...", "file": "/abs/path/cover.png" } }

这会使用 tag: "product" 上传，并将返回的文件 id 附加为商品的 imageId。手动操作是先用 tag: "product" 或 "listinggallery" 调用 vrchat__uploadImage，然后用其返回的 id 调用 vrchat__updateProduct。

VRChat 本身不允许的一件事是：列表只暴露 active 供编辑，因此其价格、标题和描述在创建后无法更改。删除列表并创建一个新的。名称、描述和图片位于商品上，可以通过 vrchat__updateProduct 编辑。

分页

每次调用一页。分页工具默认为 25 条结果，并回显一个 nextOffset 以继续。故意没有内部翻页循环：隐藏的自动分页会烧掉请求预算和大量上下文，而代理看起来就像一次调用。

短页面意味着结束。VRChat 不报告总数，所以这是唯一可靠的信号。

WebSocket 事件

默认关闭，因为空闲的常驻套接字会消耗一个会话槽位。设置 VRCHAT_MCP_WEBSOCKET=1 以打开它并注册四个 vrchat_events* 工具。

VRCHAT_MCP_WS_EVENTS 选择要订阅的类型，替换而不是扩展默认集：notification、notification-v2、economy-update、friend-online、friend-offline 和 instance-queue-ready。

管道消息是双重编码的：content 字段是字符串化的 JSON，需要第二次解析，但 see-notification 和 hide-notification 除外，它们携带裸 id。所有这些在摄取时都会被规范化一次，所以不会有工具把 JSON 字符串塞进 JSON 里。SDK 自己的套接字会静默丢弃这两种消息类型，这就是此服务器不使用它的原因之一。另一个原因是它不接受代理。

保留是按类型进行的

历史记录进入 SQLite 的 .vrchat-mcp/events.db，它按事件类型保留 1000 个事件，而不是总共 1000 个。像 friend-location 这样话多的类型永远不会驱逐像 economy-update 这样稀有而有价值的类型，而全局上限会在几分钟内做到这一点。

VRCHAT_MCP_HISTORY=1000,friend-location:200,economy-update:5000
VRCHAT_MCP_HISTORY_MAX_AGE=7d

年龄上限与数量上限同时运行，先到者获胜。仅靠数量会让很少触发的类型保留数月前的事件，而这些事件读起来像是最新的。仅靠年龄会让突发流量撑爆数据库。vrchat_eventsStatus 报告当前哪个限制在起作用，按类型区分，因此窗口是可见的而不是静默的。

历史记录在重启后仍然存在，所以 vrchat_eventsSearch 可以回答你不在时发生了什么。仅限在线的缓冲区做不到。

代理

VRCHAT_MCP_PROXY 通过 HTTP 或 HTTPS 代理路由流量，支持可选的 user:pass@ 凭据。

VRCHAT_MCP_PROXY=http://127.0.0.1:8080
VRCHAT_MCP_PROXY=https://user:pass@proxy.internal:8443

不支持 SOCKS。Bun 的 fetch 会直接拒绝 socks5://，因此 SOCKS URL 在启动时就会以配置错误失败，明确指出该限制，而不是半可用状态。请改用本地 HTTP 代理作为前置。

代理同时覆盖 API 和 WebSocket 流量。两者走不同的机制，如果只做对一半，失败模式就是服务器看起来已代理，却在事件流上泄露真实 IP。

如果无法访问代理，调用会以明确的错误失败。服务器绝不会静默回退到直连，因为对任何用此功能做 IP 隔离的人来说，那是最糟糕的结果。代理 URL 永远不会被记录，因为它可能内嵌凭据。

开发

bun link                    # install the vrchat-mcp command on PATH
bun unlink                  # remove it
bun run generate            # regenerate tools from the latest upstream spec
bun run generate --offline  # regenerate from the committed snapshot, no network
bun test                    # offline suite
bun run test:live           # live suite, needs VRCHAT_LIVE_TESTS=1
bun run inspect             # MCP Inspector against this server
bun run typecheck           # tsc --noEmit

bun run generate 从 main 分支获取 vrchatapi/specification，打包它，并将打包后的规范连同 spec/VERSION.json（上游 SHA、时间戳、内容哈希）写入，与重新生成的 src/generated/operations.ts 放在一起。两者都会被提交，因此每次重新生成都会产生两个可审查的差异：规范变更及其导致的工具变更。糟糕的上游提交可以回退，而不是成为负担。--offline 可以在完全不联网的情况下，从已提交的快照逐字节复现输出。

src/generated/operations.ts 是生成的。请勿手动编辑。

有十个 operationId 在 VRChat SDK 中没有对应的方法，因为规范比客户端库更新更快。这些通过同一客户端上的原始请求回退来路由，因此 cookie、User-Agent、代理和速率限制仍然生效，1:1 覆盖保持真实，而不是悄悄变成谎言。Codegen 每次运行都会打印该列表。

stdout 是 JSON-RPC 通道。所有日志都输出到 stderr，一个多余的 console.log 就会破坏协议流。

测试

bun test 是离线测试套件：codegen 输出、门控、针对假时钟的速率限制器、历史保留与搜索、投影、错误映射、上传路径处理。无网络、无凭据、无账户。这是默认运行的测试。

bun run test:live 会访问真实账户，通过 VRCHAT_LIVE_TESTS=1 选择加入，否则跳过。它对自己遵守的规则：

• 只读和创作者自有写入。在客户端构建之前，它就硬性拒绝任何归类为 money 或 admin 的操作。测试套件绝不能能够花钱。

• 每次写入都会自行清理并打上标签，以便游戏内可识别散落的产物。

• 它与生产环境走同一个限制器，并保持小规模。一次触发 VRChat 限流的运行比不运行更糟。

• 断言针对形状和状态，绝不针对易变内容。好友数量和世界列表会在不同运行之间变化。

• 尽可能使用专用账户。凭据仅来自 .env。

安全

• .env 和 .vrchat-mcp/ 被 gitignore 忽略，.vrchat-mcp/ 内部也忽略自身，因此它在其他项目中保持隐藏。

• .vrchat-mcp/session.json 是认证凭据，一个有效的会话 cookie。请像对待密码一样对待它。删除它，或调用 vrchat_logout，会强制重新登录。

• 2FA 验证码、密码、TOTP 密钥和代理 URL 永远不会被记录，包括 stderr。

• 你的会话 cookie 只发送到 api.vrchat.cloud，不会发送到其他地方。上传到 VRChat 的存储提供商以及从其 CDN 获取图片，都刻意绕过已认证的客户端。

• 错误以结构化结果返回，包含状态、VRChat 自身的消息和可操作的提示。原始异常和堆栈跟踪永远不会到达对话记录。

• 仅 stdio，仅本地。无 HTTP 传输，无多用户凭据隔离。此服务器面向单台机器上的单个账户。

项目结构

scripts/generate-tools.ts     # build-time codegen: spec -> src/generated/operations.ts
spec/openapi.bundled.json     # committed snapshot of the upstream spec
spec/VERSION.json             # upstream SHA + fetch timestamp + content hash
src/config.ts                 # the entire env surface, read once
src/types.ts                  # shared contracts
src/generated/operations.ts   # committed, generated, 297 entries, do not edit
src/vrchat/client.ts          # lazily-authed VRChat client, proxy, 2FA sniffing
src/vrchat/twofactor.ts       # pending-code broker
src/vrchat/ratelimit.ts       # token bucket + global 429 backoff
src/vrchat/events.ts          # websocket client + waiter registry
src/vrchat/history.ts         # bun:sqlite event store, per-type retention + FTS5 search
src/tools/auth.ts             # authStatus / submitTwoFactorCode / retryLogin / logout
src/tools/images.ts           # getImage
src/tools/upload.ts           # uploadFile / setProductImage
src/tools/events.ts           # eventsRecent / eventsWait / eventsSearch / eventsStatus
src/registry.ts               # gating, registration, the one shared handler
src/project.ts                # _responseKeys path projection
src/upload.ts                 # local path -> File, with size and type guards
src/errors.ts                 # HTTP status -> structured tool error with hint
src/index.ts                  # serveStdio entry point
tests/                        # offline suite; tests/live/ is the opt-in live suite
docs/PLAN.md                  # design document
PROGRESS.md                   # build status and verified SDK behaviour

许可证

参见 LICENSE。