Ui.Vision MCP

Ui.Vision MCP

Ui.Vision MCP は、OCR、画像認識、実際のマウスとキーボード入力を使ってブラウザーとデスクトップを自動化する MCP サーバーです。あらゆる MCP クライアント（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、LM Studio）を、Ui.Vision RPA ブラウザー拡張機能と Ui.Vision for Desktop アプリに接続します。エージェントは自動化スクリプト（uiv.* API を使用する JavaScript）を作成して実行し、ログとスクリーンショットを確認しながら繰り返し改善します。Web ページは DOM または Chrome の信頼された入力（CDP）を通じて操作し、デスクトップアプリケーション、レガシー Windows ソフトウェア、リモートデスクトップ、Citrix、PDF、キャンバス、動画など、画面上のそれ以外の要素はすべて OCR と画像検索を使って視覚的に操作します。このように画面レベルで操作できる点が、Playwright MCP や Chrome DevTools MCP などの DOM のみを対象とするサーバーとの違いです。

npm パッケージ：uivision-mcp-bridge。このプロセスはブリッジとして、MCP ツール呼び出しをローカル WebSocket 経由で拡張機能に中継し、そこで実行します。

npx uivision-mcp-bridge --setup

を実行すると、マシン上で見つかったすべての MCP クライアントにサーバーが登録されます。その後、Ui.Vision のサイドパネルでブリッジを有効にしてください（Settings → AI）。詳細はセットアップをご覧ください。

ツール

このサーバーは、拡張機能に組み込まれた AI チャットと同じツールを公開します。create_macro、set_macro、run_macro、browser_snapshot、screenshot、画像認識ヘルパー（save_element_image、save_relative_image）に加え、list_macros／open_macro／delete_macro（エージェントが作成したマクロのクリーンアップ。「AI Generated」フォルダー内のものに限定）、get_authoring_guide（uiv.* JS API リファレンス。クライアントは最初のマクロを作成する前にこれを読み込みます。JS スクリプトマクロが推奨形式です）、open_panel、select_browser、bridge_status、reload_extension、run_selftest（Settings > Desktop Automation のすべてのセルフテストを1回の呼び出しで実行します。SELFTEST: ALL OK または SELFTEST: PROBLEMS FOUND と、テストごとに1行の結果を返します。マクロが正しく動作しない場合に最初に実行してください。同じレポートは、サポート、フォーラム、または MCP を使わない AI に共有するため、Settings の「Copy report」ボタンから取得できます）、さらにデスクトップ用の click_at／type_at があります。マクロの実行時に Web ページのタブが開いていない場合、拡張機能は自動的に https://ui.vision をプレイタブとして開きます。

ブリッジがツール呼び出しを実行している間、サイドパネルには 「Claude (MCP) is controlling Ui.Vision」 というバナーが表示されます。また、エディターで現在開いているマクロがセッションで最後に開いたマクロと異なる場合、run_macro／set_macro は実行を拒否します。これにより、エージェントがユーザーがその間にパネルで切り替えたマクロを、気づかれないまま実行または編集することはありません。

run_macro では、実行対象を明示的に指定します。macro（list_macros で取得した保存済みマクロ名。開いてから実行）または script（インライン JS を直接実行し、保存しない）を指定します。どちらも指定しない場合は、上記の競合チェックを行ったうえで、エディターに表示されているマクロを実行します。

仕組み

Claude Code  ── MCP (stdio) ──►  uivision-mcp-bridge.js  ◄── WebSocket (127.0.0.1) ──  Ui.Vision extension

ブリッジは接続の中継点です。Claude Code が MCP サーバーとしてブリッジを起動し、拡張機能のサイドパネルがローカル WebSocket サーバーに接続します（ブラウザー拡張機能は着信接続を受け付けられないためです）。ツール呼び出しは拡張機能に転送され、そこで実行されます。

ブリッジの接続中、サイドパネルにはタブの上に紫色の MCP: chrome#1 ストリップが表示されます（拡張機能 10.0.183 以降）。ここには、接続ラベル、ブリッジの接続元クライアント（「Claude connected」、「LM Studio connected」など。ブリッジ 1.7.9 では親プロセスから取得し、10.0.215 以降で表示）、現在実行中のツール、赤色の STOP ボタンが表示されます。STOP を押すと実行中のマクロを停止し、実行中の呼び出しに「stopped by the user」と応答して、ブリッジをオフにします（再度有効にするには Settings > AI を開きます）。接続時にパネルは Data > Logs に切り替わり、ブリッジに関する各行には [MCP] が付与されます。

ブリッジ 1.7.13 以降では、呼び出し元のラベルに MCP の initialize.clientInfo.name を使用し、親プロセスの検出はフォールバックとしてのみ使用します。中継された呼び出しは、初期化が中継ハンドシェイクの後に行われる場合でも、それぞれの呼び出し元の名前を保持します。名前のない中継元は「MCP client」と表示され、ブリッジ所有者のクライアント名が表示されることはありません。

セットアップ

1. インストーラーを実行します。ターミナルで一度実行すれば、npm がブリッジを自動的に取得します。

   npx uivision-mcp-bridge --setup
   

   この操作により、マシン上で検出されたすべての MCP クライアントに uivision サーバーエントリーが追加されます。対象は Claude Code（~/.claude.json）、Claude Desktop、Cursor、Windsurf、VS Code です。その後、手順 2 で使うペアリングトークンが表示されます。既存の設定は置き換えずに統合され、先に .uivision-backup コピーが作成されます。無効な JSON の設定ファイルは報告され、そのまま変更されません。

   --setup が用意されているのは、claude mcp add ... の実行に必要な claude CLI が PATH 上にないためです。デスクトップアプリ、VS Code 拡張機能、Cursor、Windsurf にはこの CLI がありません。インストーラーが認識しないクライアントの場合は、手動で追加してください（VS Code では "mcpServers" ではなく "servers" の下にネストします）。

   { "mcpServers": { "uivision": { "command": "npx", "args": ["-y", "uivision-mcp-bridge"] } } }
   

   このリポジトリのチェックアウトから作業する場合は、代わりに cd mcp && npm install を実行し、node /absolute/path/to/mcp/uivision-mcp-bridge.js を登録します。

   MCP クライアントは起動時にサーバーを読み込みます。登録したら、クライアントを完全に終了してから再度開き（新しいセッションやタブを開くだけでは不十分です）、/mcp で uivision が一覧に表示されることを確認してください。--setup が設定を書き込んでいる間にクライアントが起動していた場合は、終了してから --setup をもう一度実行してください。一部のクライアントは終了時に設定を書き換えるため、エントリーが削除されることがあります。

2. Ui.Vision でブリッジを有効にします。Ui.Vision のサイドパネルを開き、Settings → AI → MCP bridge (Claude Code) の順に進んで有効にします。ポートは、変更していない限りデフォルトのまま（50888）にして、Test をクリックします。

   現在のブラウザーではペアリングトークンは不要です（bridge 1.7 以降）。ブラウザーは WebSocket ハンドシェイクに拡張機能のオリジンを付与します。ウェブコンテンツからこれを偽装することはできないため、ブリッジは本物の Ui.Vision 拡張機能を直接識別できます。トークン欄はフォールバックとして残されています。Test でトークンが必要と表示された場合に限り入力してください（古いブリッジを使っている場合、またはオリジンを送信しない接続の場合です）。開発／テスト用ブラウザー（パッケージ化されていない拡張機能や一時読み込みの拡張機能、Firefox Developer／Beta ビルド）では、ブリッジのスイッチもデフォルトで ON になります。ストアからインストールした拡張機能では、引き続きオプトインが必要です。

   フォールバック用のトークンが必要ですか？~/.uivision_mcp_token にあります。--setup を実行すると再度表示されます。または、AI に尋ねるだけでもかまいません。拡張機能が未ペアリングの間は、ブリッジツールの結果に毎回トークン値が含まれるため、エージェントはファイルを読み取らずにチャットで表示できます。

3. サイドパネルを開いたままにします。ツールはサイドパネルのコンテキストで実行されます。閉じていると、ツールの呼び出しは「extension not connected」を返します。

   必要なときは AI が自分でパネルを再度開きます（拡張機能 10.0.170 以降、bridge 1.5 以降）。拡張機能はブリッジへの軽量なバックグラウンドのウェイクチャネルを維持し、open_panel ツールでこのチャネルを通じて Ui.Vision アプリをタブで開きます。ブラウザーがウィンドウなしでトレイにある場合でも開きます（ウィンドウが作成されます）。拡張機能が独自に何かを開くことはありません。再度開く操作は常にエージェントが明示的に行います（意図的な例外として、エージェント自身が reload_extension を実行した後はパネルが自動的に戻り、ビルド・再読み込み・検証のサイクルが完了します）。ブラウザープロセス自体が起動していない場合は、エージェントがシェルから起動し（start chrome）、ウェイクチャネルが利用可能になるまで数秒待ってから open_panel を呼び出します。そのため、ブラウザーが完全に終了している状態からマクロの実行を始められます。手動でパネルを閉じると、エージェントが明示的に再表示を求めるまで、すべての動作が一時停止します。パネルの Logs タブには、再表示のたびに「[MCP] panel reopen trace」と記録されます。

あとは Claude Code でチャットするだけです。「Ui.Vision を使って example.com にログインし、レポートをダウンロードするマクロを作成して」と依頼すると、Claude がマクロを作成して実行し、ログを読み、調整を重ねます。サイドパネルで処理の様子をリアルタイムに確認できます。

LM Studio（ローカルモデル、クラウド不要）

LM Studio のチャット（0.3.17+）も MCP クライアントなので、ローカルモデルで Ui.Vision を同じように操作できます。サーバーを ~/.lmstudio/mcp.json に追加します（スラッシュを使用してください。Windows のバックスラッシュを含むパスは有効な JSON ではありません）。

{ "mcpServers": { "uivision": { "command": "npx", "args": ["-y", "uivision-mcp-bridge"] } } }

LM Studio は再起動なしでファイルを読み込みます。チャットで、右側のサイドバーにある Integrations タブを開き、mcp/uivision をオンにします。最初のツール呼び出しでブリッジが起動します。Always allow any tool from mcp/uivision にチェックを入れない限り、LM Studio は呼び出しごとに Proceed / Deny を尋ねます。ツール呼び出しとビジョンに対応し、大きなコンテキストで読み込んだモデルを選んでください。2026-09-06 に、24 GB GPU 上で Qwen3.6-27B（Q4_K_M）を lms load qwen/qwen3.6-27b --gpu max -c 65536 --parallel 1 として読み込み、動作を確認しています（--parallel 1 が重要です。デフォルトの 4 スロットでは KV キャッシュが乗算され、システム RAM にあふれます）。Claude Code のブリッジがすでにポート 50888 を使用している場合、LM Studio 側のブリッジはそれを経由するリレーとなり、両方のクライアントが 1 つの拡張機能を共有します。

同じ LM Studio サーバーは、拡張機能内のチャットモデルとしても使用できます。Settings > AI > Local — OpenAI-compatible を開き、ベース URL を http://localhost:1234/v1、モデルを LM Studio の識別子に設定します。チャットの指示だけで約 40k トークンあるため、モデルには 64k 以上のコンテキストウィンドウが必要です。

オプション

オプション	デフォルト	説明
--setup	—	1 回限りのインストーラーです。マシン上のすべての MCP クライアントにブリッジを登録し、ペアリングトークンを表示して終了します。サーバーは起動しません。--port と組み合わせると、デフォルト以外のポートを登録できます。
--port <n> / UIVISION_MCP_PORT	50888	WebSocket ポート（127.0.0.1 のみ）。Ui.Vision の設定にあるポートと一致させる必要があります。
--token <t> / UIVISION_MCP_TOKEN	自動生成	共有シークレットです。指定しない場合、ユーザーのホームディレクトリにある .uivision_mcp_token に自動保存されます。

ブラウザーのサポート

Chrome（サイドパネル）と Firefox（サイドバー。同じパネルコード）で動作確認済みです。Firefox 154 で 2026-07-28 にテストし、接続とトースト表示、すべての uiv.* ガードエラー、{area} に限定した視覚検索での正しい座標の再基準化、shot.area の記述が、すべて同じように動作することを確認しています。uiv.browser.*（CDP の信頼された入力）を操作するマクロは引き続き Chrome のみで使用できます。Firefox では uiv.page.* / uiv.desktop.* を使用してください。

複数のブラウザーを同時に使用（bridge 1.4+）

bridge 1.7.10 以降、select_browser は MCP クライアントごとに機能します。Claude Code と LM Studio が 1 つのブリッジを共有している場合、それぞれが独自の接続先を維持します（LM Studio が Chrome を操作する一方で、Claude Code は Edge を監視できます）。select_browser を一度も呼び出していないクライアントは、最新の接続を使用します。同じビルドの Chrome と Edge は同じ拡張機能 ID を報告するため、ブリッジはブラウザーの種類で両者を区別する点に注意してください。

すべてのブラウザーと、そのインスタンスまたはプロファイルはそれぞれ個別にブリッジへ接続します。接続順に family#n というラベルが付きます（chrome#1、chrome#2、firefox#1 など）。ラベルは拡張機能のパネルのフッター（MCP: chrome#1）と Settings > AI に表示されるため、各インスタンスをすぐに見分けられます。ツール呼び出しは アクティブな接続先、デフォルトでは最後に接続したブラウザーに送られます。select_browser ツールで切り替えられます（"firefox" のようにブラウザーの種類だけを指定すると、その種類の最新のものが選択され、"chrome#2" のように指定すると、特定のインスタンスに固定されます）。また、bridge_status にはすべての接続が表示され、アクティブな接続には印が付きます。1 つのブリッジ経由で Chrome と Firefox が Core のデモセット全体を並行して実行することを、実際の環境で確認済みです。

open_panel（bridge 1.7.3+）は拡張機能のオリジンでインスタンスを区別するため、同じブラウザー内に拡張機能が 2 つある場合（たとえば、同じ Chrome に Web Store 版と展開済みの開発版がある場合）も、それぞれ個別に起動できます。Web Store 版が接続されていても、open_panel を使うと展開済みの開発版のパネルが再び開きます。bridge_status には各起動チャネルの拡張機能 ID が表示されます。

セキュリティ

• WebSocket サーバーは127.0.0.1のみにバインドされます。ネットワークからアクセスできるものはありません。
• 接続はオリジンで認証されます。ブラウザーはハンドシェイクに拡張機能のオリジンを付与し、Web コンテンツから偽装することはできないため、ブリッジはトークンなしでファーストパーティの Ui.Vision 拡張機能（許可リストに登録されたchrome-extension://…の ID、または任意のmoz-extension://…）を受け入れます。Web ページのオリジンはそのサイトであるため、127.0.0.1に接続しようとするページは拒否されます。また、ソケットは転送されたツール呼び出しを受信することしかできず、自ら呼び出すことはできません。オリジンを持たない接続（ローカルのネイティブクライアント）は、引き続き共有トークンで認証されます。5 秒以内に認証されない場合は切断されます。悪意のあるネイティブプロセスはオリジンヘッダーを偽装できますが、そのプロセスはすでにマシンに完全にアクセスできるため、このケースでは何も変わりません。
• 拡張機能には、内蔵 AI チャットと同じガードレールが適用されます。ユーザーのマクロファイルは上書きされず（編集内容は「AI Generated」フォルダーにコピーとして保存されます）、プリインストールされたデモマクロは明示的な確認なしには実行されません。

トラブルシューティング

• セッションにuivisionツールがまったくない場合：--setupの後にクライアントを再起動していないか、--setupが設定を書き込んでいる間にクライアントを起動していた可能性があります。クライアントを完全に終了し、--setupを再実行してから、再度開いてください。
• Claude にbridge_statusツールを呼び出すよう依頼してください。このツールは拡張機能が接続されているかどうかを報告し、ペアリング前にはペアリングトークンを返します。
• ブリッジのログは stderr に出力されます（claude --debugまたは Claude Code の MCP ログで確認できます）。
• Claude Code のウィンドウを複数同時に開いている場合（ブリッジ 1.7.5 以降）：各ウィンドウが独自のブリッジを起動しますが、ポートを使用できるのは 1 つだけです。他のウィンドウはリレーモードに切り替わり、ツール呼び出しを使用中のブリッジ経由で転送するため、すべてのウィンドウでツールを使用できます。bridge_statusには、ウィンドウがリレー中であることが表示されます。ポートを使用しているウィンドウを閉じると、リレーがポートを引き継ぎます。
• ポートを古いバージョンのブリッジ（1.7.5 より前）が使用していて「Port in use」と表示される場合：ログにポートを使用している pid が記載されています。そのウィンドウで MCP サーバーを再起動するか、ウィンドウを閉じてください。または、別の--portを選び、Ui.Vision の設定も更新してください。