Ui.Vision MCP

Ui.Vision MCP

Ui.Vision MCP 是一个用于浏览器和桌面自动化的 MCP 服务，支持 OCR、 图像识别以及真实的鼠标和键盘输入。它将任意 MCP 客户端 ——Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、LM Studio——连接到 Ui.Vision RPA 浏览器扩展和 Ui.Vision for Desktop 应用。Agent 编写自动化脚本（使用 uiv.* API 的 JavaScript），运行脚本，读取日志和屏幕截图，然后不断迭代。网页通过 DOM 或 Chrome 的可信输入（CDP）进行操作；屏幕上的其他所有内容——桌面应用、旧版 Windows 软件、远程桌面、 Citrix、PDF、画布和视频——均通过 OCR 和图像搜索进行视觉操作。这种屏幕级覆盖能力使它区别于 Playwright MCP 或 Chrome DevTools MCP 等仅支持 DOM 的服务。

npm 包：uivision-mcp-bridge。该进程是一个桥接程序：它通过本地 WebSocket 将 MCP 工具调用中继到扩展，并在那里执行。

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（清理 Agent 创建的 宏——仅限“AI Generated”文件夹）、get_authoring_guide（uiv.* JS API 参考——客户端在编写第一个宏前会先读取；JS 脚本宏是首选形式）、open_panel、select_browser、 bridge_status、reload_extension、run_selftest（一次调用运行 Settings > Desktop Automation 中的每项自检，返回 SELFTEST: ALL OK 或 SELFTEST: PROBLEMS FOUND，并为每项测试提供一行结果——宏运行异常时首先应运行此项；相同的报告也可通过 Settings 中的“Copy report”按钮获取，以便提供给支持人员、论坛或不使用 MCP 的 AI），以及桌面工具 click_at / type_at。如果运行宏时没有打开网页标签页，扩展会自动打开 https://ui.vision 作为播放标签页。

桥接程序执行工具调用期间，侧边栏会显示 “Claude (MCP) is controlling Ui.Vision” 横幅；如果编辑器中显示的宏已不是该会话上次打开的宏，run_macro / set_macro 将拒绝执行，因此 Agent 无法在用户随后切换到其他宏的情况下，悄悄运行或编辑该宏。

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”——bridge 1.7.9 会从其父进程读取该信息；10.0.215+ 会显示该信息）、当前正在执行的工具，以及红色的 STOP 按钮。STOP 会停止正在运行的宏，以“stopped by the user”作为正在进行的调用的响应，并关闭桥接功能（如需重新启用，请前往 Settings > AI）。连接后，面板会切换到 Data > Logs；其中每一条桥接日志行都带有 [MCP] 标记。

bridge 1.7.13+ 使用 MCP initialize.clientInfo.name 作为调用方标签，仅在无法获取时才通过父进程检测作为后备。即使初始化发生在中继握手之后，中继调用也会保留各自的调用方名称。未命名的中继会显示为“MCP client”，而不会显示为桥接程序所属客户端。

设置

1. 运行安装程序：在终端中运行一次（npm 会自动获取桥接程序）：

   npx uivision-mcp-bridge --setup
   

   安装程序会将 uivision 服务条目写入它在计算机上找到的每个 MCP 客户端中——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 中并没有它。对于安装程序不识别的客户端，请手动添加（VS Code 将其嵌套在 "servers" 下，而不是 "mcpServers" 下）：

   { "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 侧边栏 → 设置 → AI → MCP bridge (Claude Code) → 启用它；除非你已更改端口，否则请保留默认端口（50888），然后点击 测试。

   当前浏览器无需配对令牌（桥接程序 1.7+）：浏览器会在 WebSocket 握手中附上扩展程序的来源，网页内容无法伪造，因此桥接程序可以直接识别真正的 Ui.Vision 扩展程序。令牌栏会保留作为备用方案——只有当 测试 提示需要令牌时才填写（可能是桥接程序版本较旧，或连接未发送来源）。开发/测试浏览器（未打包/临时加载的扩展程序，或 Firefox Developer/Beta 版本）还会默认启用桥接开关；商店安装版本则保留选择加入开关。

   需要备用令牌？它位于 ~/.uivision_mcp_token；--setup 会再次打印它；或者直接询问 AI——当扩展程序尚未配对时，每个桥接工具结果都会包含令牌值，因此 Agent 可以在聊天中显示给你，而无需读取任何文件。

3. 保持侧边栏打开——工具会在侧边栏上下文中执行。如果侧边栏已关闭，工具调用会返回“扩展程序未连接”。

   需要时，AI 会自行重新打开侧边栏（扩展程序 10.0.170+ 搭配桥接程序 1.5+）：扩展程序会与桥接程序保持一个轻量的后台唤醒通道，而 open_panel 工具会通过该通道在标签页中打开 Ui.Vision 应用——即使浏览器在系统托盘中且没有任何窗口也可以（此时会创建一个窗口）。扩展程序绝不会自行打开任何内容：重新打开侧边栏始终是 Agent 明确执行的操作（唯一的特例是：Agent 自行调用 reload_extension 后，侧边栏会自动恢复，以便完成构建-重新加载-验证循环）。如果浏览器进程本身未运行，Agent 会从 Shell 启动它（start chrome），等待几秒钟让唤醒通道就绪，然后调用 open_panel——因此，即使浏览器完全关闭，宏也可以开始运行。手动关闭侧边栏仍会暂停所有操作，直到 Agent 明确要求重新打开；侧边栏的“日志”标签页会将每次重新打开记录为“[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 的副本会通过它中继——两个客户端共用同一个扩展。

同一个 LM Studio 服务也可作为扩展内的聊天模型：Settings > AI > Local — OpenAI-compatible，基本 URL 为 http://localhost:1234/v1，model = LM Studio 标识符。聊天指令本身约有 40k 个 token，因此模型需要 64k+ 的上下文窗口。

选项

选项	默认值	说明
--setup	—	一次性安装程序：向此计算机上的每个 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（侧边栏，使用相同的面板代码）上验证——2026-07-28 在 Firefox 154 上测试：连接 + 提示消息、所有 uiv.* 防护错误、受 {area} 限定且坐标重新映射正确的视觉查找，以及 shot.area 编写，表现都相同。驱动 uiv.browser.*（CDP 可信输入）的宏仍仅支持 Chrome；在 Firefox 上请使用 uiv.page.* / uiv.desktop.*。

同时使用多个浏览器（桥接程序 1.4+）

从桥接程序 1.7.10 起，select_browser 按 MCP 客户端分别生效：Claude Code 和 LM Studio 共用一个桥接程序时，各自保留自己的目标浏览器（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 会列出所有连接，并标记活动连接。已进行实时验证：Chrome 和 Firefox 通过一个桥接程序并行运行完整的 Core 演示套件。

open_panel（桥接程序 1.7.3+）根据扩展来源区分实例，因此同一浏览器中的两个扩展副本——例如同一 Chrome 中的 Web Store 版本和未打包的开发版本——会分别唤醒：即使 Web Store 副本已连接，open_panel 仍会重新打开未打包版本的面板。bridge_status 会显示每个唤醒通道的扩展 ID。

安全

• WebSocket 服务仅绑定到 127.0.0.1——网络无法访问。
• 连接通过来源进行身份验证：浏览器会在握手中标记扩展程序的来源，网页内容无法伪造，因此桥接服务无需令牌即可接纳第一方 Ui.Vision 扩展程序（列入允许列表的 chrome-extension://… ID，或任意 moz-extension://…）。网页的来源是其网站，因此拨号连接 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+）：每个窗口都会启动自己的桥接服务，但只有一个能占用端口。其他窗口会切换到中继模式，并通过端口所有者转发其工具调用，因此每个窗口都能正常使用工具。bridge_status 会显示窗口何时处于中继模式。拥有端口的窗口关闭后，中继窗口会接管端口。
• 端口被较旧版本的桥接服务占用（早于 1.7.5）时出现 "Port in use"：日志会显示占用端口的 pid；重启该窗口中的 MCP 服务，或关闭该窗口。也可以选择其他 --port（并在 Ui.Vision 设置中更新）。