VRChat MCP

VRChat MCP

VRChat のフレンド、ワールド、グループ、イベント、通知、ステータス、招待、ローカルの VRCX 履歴を扱う非公式のローカル Model Context Protocol ツールです。

VRChat MCP はデフォルトで stdio を通じてローカルで実行され、オプトインでループバック専用の Streamable HTTP モードも利用できます。VRChat の認証 Cookie はお使いのマシンに保管され、デフォルトでは OS のキーチェーンに保存されます。キーチェーンのバックエンドが利用できない場合は、ファイルに保存されます。厳選された書き込みツール、生成された読み取り／書き込みツール、読み取り専用の VRCX ローカル履歴ツールをデフォルトで利用できます。アカウントを変更するツール呼び出しは、MCP クライアントまたはエージェントのハーネスを使って承認してください。

このプロジェクトは非公式であり、VRChat Inc. とは提携していません。

ポリシーと安全上の境界

VRChat は、サードパーティ API アプリケーション向けの公開 OAuth フローを提供していません。VRChat の Creator Guidelines では、API アプリケーションは VRChat のログイン認証情報、認証トークン、セッションデータを要求または保存してはならないこと、明確な User-Agent を使用して自身を識別すること、制限のないリクエストを送信するのではなくキャッシュやバックオフを行うこと、他のユーザーに代わって操作しないことが定められています。

そのため、このプロジェクトはユーザー自身が制御するローカルな個人用ツールとしてのみ使用することを想定しています。ホスト型／公開 MCP サービスとして実行しないでください。他人の認証情報や Cookie を収集したり、スパムや嫌がらせを自動化したり、VRChat の執行措置やモデレーションを回避するために使用したりしないでください。書き込みツールは、VRChat で自分自身が意図的に行う操作にのみ使用してください。

インストール

要件：

• Node.js 24.15.0 以降。
• ローカルの stdio サーバーを実行できる MCP クライアント。
• キーチェーンおよび VRCX の SQLite サポート向けのネイティブ依存関係がインストールされていること（keytar、better-sqlite3）。

libsecret などのキーチェーンデーモンがないヘッドレス Linux またはコンテナでは、Cookie を明示的に永続保存するために VRCHAT_MCP_COOKIE_STORE=file を設定してください。

通常は 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 では mcpServers ではなく servers オブジェクトを使用します。

.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 クライアントで、1 つのローカル 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 のトークンをベアラートークンとして送信します。トークンは環境変数またはシークレットストアに保存してください。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 を呼び出してセッションを確認します。デフォルトでは、MCP サーバーを再起動してもログイン状態が維持されるように、Cookie は OS のキーチェーンに保存されます。OS のキーチェーンが利用できない場合、VRChat MCP はファイルストレージにフォールバックします。

このログインフローを他の人に代わりに使ってもらわないでください。ローカルのログイン URL、Cookie、セッションファイルを、ホスト型ツールやサードパーティサービスに送信しないでください。

便利な認証ツール：

• vrchat_auth_begin：ローカルのブラウザーログインを開始します。
• vrchat_auth_status：サーバーにログインしているか確認します。
• vrchat_auth_logout：保存されたセッションを消去します。

ボットアカウントのヘッドレスログイン

ブラウザでのログインには人の操作が必要です。VRChat の twoFactorAuth Cookie の有効期間は 30 日間で、アカウントの 2FA 方式を変更するとセッションがただちに無効になるため、無人で運用する場合は、そのたびに誰かが再ログインする必要があります。認証アプリ（TOTP）による 2FA を設定した、自分が所有して運用するアカウント（専用のボットアカウントなど）であれば、サーバーが自動で再ログインできます。

有効にするには、3 つすべての変数を設定してください。いずれかが設定されていない、または空の場合は、動作は変わりません。

変数	用途
VRCHAT_MCP_USERNAME	VRChat のユーザー名またはメールアドレスです。
VRCHAT_MCP_PASSWORD	VRChat のパスワードです。
VRCHAT_MCP_TOTP_SECRET	Base32 形式の認証アプリのシークレットです。VRChat で使われる、スペースで区切られた小文字の形式も使用できます。

VRChat API へのリクエストが 401 を返すと、サーバーはパスワードと新たに生成した TOTP コードを使って 1 回ログインし、設定済みの Cookie ストアに新しい Cookie を保存してから、リクエストを 1 回再試行します。VRChat が TOTP ではなくメールコードを要求した場合、サーバーはコードを送信せず、vrchat_auth_begin を使用するよう案内するメモを含む通常の 401 エラーを返します。VRChat はパスワードの入力後にのみ 2FA 方式を明らかにするため、この場合も下記のバックオフにおける失敗として扱われます。

自動ログインにはレート制限があり、ホストが呼び出しごとに新しいサーバープロセスを起動する場合にも制限が維持されるよう、制限の状態は保存されます。

• 自動試行は 10 分ごとに最大 1 回です。
• 失敗（パスワードの誤り、コードの拒否、VRChat のエラーなど）の後は、60 分間、自動試行は行われません。ログイン中にプロセスが終了するなど、試行の結果が記録されなかった場合も失敗として扱われます。
• クールダウン中は、ツールエラーにその旨と次回試行可能な時刻が示されます。
• 記録ファイルは、設定済みの Cookie ファイルパスと同じ場所にある <cookie file>.autologin.json（モード 0600）です。キーチェーンストレージでも同じパスを使用します。短時間だけ存在する .lock ファイルにより、2 つのプロセスが同じ試行を実行しないようにします。記録を書き込めない場合、サーバーはログインを試みません。
• VRCHAT_MCP_COOKIE_STORE=memory の場合はファイルがないため、制限はメモリ内に保持され、1 つのプロセス内でのみ適用されます。これは制限としてかなり弱く、呼び出しごとにプロセスが起動する場合、毎回ログインが行われます。ヘッドレス環境では file ストレージを使用してください。

パスワード、TOTP シークレット、生成されたコード、Cookie の値がログに記録されたり、ツールの結果やエラーに含まれたりすることはありません。vrchat_auth_logout は引き続きセッションを消去しますが、変数が設定されている場合、次回の API 呼び出し時に再ログインします。

OpenClaw を含む一部の MCP ホストは、子プロセスの環境変数をホスト自身の環境変数とマージせず、サーバーエントリの env ブロックで置き換えます。パスワードや TOTP シークレットをホストの設定に直接記述しないでください。これらは root 所有のモード 0600 の env ファイルに保存し、そのファイルを読み込んでサーバーを実行する小さなラッパースクリプトをホストに指定してください。ホストは、そのファイルを読み取れるユーザーとしてラッパーを実行する必要があります。シェルのメタ文字を含む値は引用符で囲んでください。ホストの env ブロックが 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 では、厳選されたツールに加えて、生成された読み取り／書き込み／削除ルーターがデフォルトで公開されます。厳選されたツールは、よくあるタスクを簡潔でエージェントが扱いやすい入力と出力で実行できます。

一般的な厳選ツールには、次のものがあります。

• 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 ギャップを補うため、次の3つのルーターツールが用意されています。

• 利用可能な GET 操作用の vrchat_read。operationId に加え、パス、クエリ、ヘッダー、Cookie の値を params に渡します。
• 利用可能な POST／PUT／PATCH 操作用の vrchat_write。operationId と params を渡し、JSON ペイロードは body に渡します。
• 利用可能な DELETE 操作用の vrchat_delete。operationId と params を渡し、任意の JSON ペイロードは body に渡します。

利用可能な生成済みの operation ID を一覧表示するには vrchat_operations を、操作ごとの正確な params／body スキーマを確認するには vrchat_operation_details を使用します。

生成された読み取りツールと書き込みツールはデフォルトで有効です。VRCHAT_MCP_DISABLE_GENERATED_READ_TOOLS=true を設定すると、vrchat_read が非表示になります。VRCHAT_MCP_DISABLE_GENERATED_WRITE_TOOLS=true を設定すると、生成された書き込みツール共通のスイッチにより、vrchat_write と vrchat_delete の両方が非表示になります。JSON 設定で、どちらのツール群も特定の operation 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 クライアントまたはエージェントのハーネスがツール呼び出しの許可、承認、拒否を制御することを想定しています。

読み取り専用モードを強制するには、MCP クライアントのサーバーエントリー内に次の env フラグメントを追加します。

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

このローカル MCP サーバーで VRChat アカウントの操作を行う場合に限り、書き込みツールを使用してください。一括ソーシャルツールには上限が設定されており、429 が返された場合は処理を控えますが、スパム、嫌がらせ、望まれない自動化を避ける責任はユーザーにあります。

vrchat_gallery_image_upload は、検証済みの静的 PNG をサインイン中のアカウントの個人ギャラリーにアップロードします。受け付けるのは imagePath のみです。グループの権限確認は、返されたファイル ID を関連付けるグループ投稿ツールまたはイベントツールで行われます。このツールを使用する前に、絶対パスを指定した uploads.allowedRoots エントリーを少なくとも1つ設定してください。

グループの書き込みツールについては、JSON 設定ファイルで書き込みを特定のグループ ID のみに制限できます。

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

次に、MCP クライアントの設定で VRCHAT_MCP_CONFIG_FILE にそのファイルパスを設定します。

設定

設定は任意です。通常のローカル利用ではデフォルト値で対応できます。

よく使う環境変数：

変数	用途
VRCHAT_MCP_CONFIG_FILE	JSON 設定ファイルへのパス。
VRCHAT_MCP_USER_AGENT	VRChat API リクエストに使用する説明的なユーザーエージェント。
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 テストと LLM 評価はオプトインです。詳細は docs/evals.md を参照してください。

ライセンス

MIT。LICENSE を参照してください。