Chrome CUA MCP
Provides tools for controlling Google Chrome: navigating pages and tabs, observing DOM content and clickable elements, clicking and typing, running multi-step browser plans, and extracting page text and links. Supports an isolated managed Chrome via CDP and a desktop Chrome window using screenshots, OCR, and real keyboard/mouse input, with safeguards for high-risk actions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Chrome CUA MCP
给没有内置 computer use 的 agent / harness 用的 Chrome 操作工具:一个 MCP 服务,加一个本地 2B 视觉模型,加一个桌面悬浮窗。上层模型只收发文字,页面由本机来看、来点。

上面是 25 秒实录,未加速、未剪辑。一个 MCP 客户端用 cua_navigate、一次 cua_run_steps(4 步)和 cua_ask_screen 操作隔离的 Chrome,全程 0 张截图;随后在悬浮窗里输入“点击右侧橙色的按钮”,本地模型定位到的是“确认支付”,动作被拦下,人确认后才点击。页面是录制脚本自带的本地演示页,没有真实交易;底部字幕是后期加的,其中的耗时、字节数和回答取自当次调用的真实返回。录制脚本:scripts/record_demo.py。
它怎么工作
两种目标
managed:独立配置目录的隔离 Chrome,通过 CDP 读 DOM、点元素。快,不碰你的日常浏览器。desktop:你已经登录的本机 Chrome,用窗口截图、Windows 自带 OCR 和真实键鼠输入。
文字优先:能用 DOM 或 OCR 文字匹配的目标不调模型;默认不回传截图,返回体默认精简(
detail="brief")。本地模型兜底:没有文字的图标、需要“看一眼”的问题,交给本机的 Qwen3.5-2B 微调模型(llama.cpp,约 2.3 GB 显存),只把坐标或一句话答案返回给上层。模型在第一次用到视觉时才加载。
批量执行:
cua_run_steps一次调用最多跑 12 步,减少上层模型的往返轮次。保护
支付、下单、删除、转账等高危词(指令里出现,或定位到的目标上出现)会停下来等人确认,返回一次性
confirm_token。登录页和人机验证直接交还给人。
desktop模式下 Chrome 不在前台就拒绝发送键鼠;把鼠标甩到屏幕左上角可急停。带
require_submit的提交步骤只认 URL 变化、明确的表单结果或你指定的新文字,输入框回显不算提交成功。
悬浮窗:平时只有一行输入;上层接入、执行进度、风险确认按需出现。也可以不经上层模型,直接在里面下单步指令。
Related MCP server: agentic-browser
现状和边界
这是一个个人项目,只在一台机器上验证过(Windows 11、RTX 4060 Laptop 8 GB、Python 3.11)。下面的数字都是小样本,不是成功率承诺。
项目 | 结果 | 说明 |
托管模式一次观察 | 2–3 ms | 不截图时 |
本地模型一次定位或读屏 | 约 0.5–0.7 s | 模型已加载;首次加载另需约 2–3 s(文件已在系统缓存里时) |
桌面模式 OCR | 约 0.7 s | 整窗 |
自采真实 Chrome 留出集:点击落框 / 缺失目标拒识 | 103/120、80/80 | 与训练数据同批采集,偏乐观 |
Venus 中文定位题(没见过的页面):点击落框 / 缺失目标拒识 | 105/240、22/80 | 泛化明显变差 |
真实网站上纯视觉找链接 | 两轮 6/15、5/15 | 不执行点击,只比对坐标 |
Python 文档站内搜索并提交(托管模式) | 10/10 | 修复回车提交后复测 |
适合:上层模型负责拆任务和核对结果,本工具负责在托管 Chrome 里按 DOM 执行;需要看图时本地模型兜底;高危动作由人确认。
不适合:无人值守的长链任务;纯视觉操作陌生网站;拖拽、画图、滑块(动作协议里没有按住拖动)。
没有验证过:除 Codex、Antigravity 以外的 MCP 客户端;上层模型实际节省了多少 token;Windows 10 和其他显卡。
微调权重没有随仓库发布。
m0_setup_local.py能下载官方基座的 GGUF,但基座不按本项目的动作协议输出(协议判分 0/24),视觉定位基本不可用;不依赖模型的 DOM 路径不受影响。要用视觉功能,需要按训练一节自己训练并导出。
环境要求
Windows 10/11,Google Chrome 装在默认位置(
C:\Program Files\Google\Chrome\Application\chrome.exe)Python 3.11
视觉功能需要 NVIDIA 显卡(llama.cpp 的 CUDA 12.4 预编译包),约 2.3 GB 显存
安装
git clone https://github.com/Assangejulian/chrome-cua-mcp.git
cd chrome-cua-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
# 可选:下载 llama.cpp(b12441,CUDA 12.4)和官方基座 GGUF 到 tools/ 与 models/
.\.venv\Scripts\python.exe .\scripts\m0_setup_local.py模型放在 models/<目录>/ 下,启动时按下表自动发现,排在前面的优先:
悬浮窗里的名字 | 目录 | 模型文件 | 视觉投影文件 |
M3.5 |
|
|
|
M3 |
|
|
|
基座 |
|
|
|
运行
悬浮窗(同时提供 HTTP MCP,http://127.0.0.1:18390/mcp)
.\启动_Chrome_Pilot_M35.bat悬浮窗启动时如果发现已打开的 Chrome,会默认选中“本机 Chrome”,之后的动作是真实键鼠输入到你的浏览器。想在隔离浏览器里操作,先点 ≡ 把第一个下拉切到“后台托管”。
只起 MCP 服务(默认 managed)
.\.venv\Scripts\python.exe .\scripts\chrome_cua_mcp.py --stdio
.\.venv\Scripts\python.exe .\scripts\chrome_cua_mcp.py --http --port 18390可选参数:--target-mode managed|desktop、--profile-dir <目录>(托管 Chrome 的配置目录,默认是项目下的 profiles/cua_chrome,里面有登录状态,已被 git 忽略)。
接入上层模型
Stdio(Codex 的 config.toml,路径换成你的克隆位置):
[mcp_servers.chrome-pilot-cua]
command = 'D:\path\to\chrome-cua-mcp\.venv\Scripts\python.exe'
args = ['D:\path\to\chrome-cua-mcp\scripts\chrome_cua_mcp.py', '--stdio']HTTP(悬浮窗或 --http 已在运行时):
{ "mcpServers": { "chrome-pilot-cua": { "url": "http://127.0.0.1:18390/mcp" } } }configs/ 里是同样的三份配置,其中的绝对路径是作者机器上的,使用前要改;悬浮窗“接入”菜单里的“复制 Stdio 配置”复制的也是这份文件。
工具
工具 | 作用 |
| 打开网址、前进后退、切换标签页,或切换 |
| 读当前页面:URL、标题、正文、可点元素(坐标为 0–1000 归一化)、是否遇到登录或验证码 |
| 执行一步:按元素编号、OCR 编号、文字提示,或用自然语言交给本地模型定位 |
| 一次最多 12 步的小计划:打开、点击并输入、滚动到、等待、提问等;遇到弹窗、高危动作、未观察到提交会停下并说明 |
| 让本地模型回答一个关于当前画面的事实问题,只返回文字 |
| 只预览本地模型的定位坐标,不发送任何输入 |
| 尝试关闭弹窗或横幅 |
| 提取页面可见文字和链接 |
| 当前模型、显存、浏览器和任务状态(不会触发模型加载) |
| 把任务的开始、进度、完成显示到悬浮窗上 |
省上层 token 的用法:能拼出网址就直接 cua_navigate;多步操作打包进一次 cua_run_steps;需要确认页面细节时用 cua_ask_screen 而不是要截图;只有排查问题时才传 include_screenshot=true 或 detail="full"。status 只表示动作是否发出、提交是否被观察到,关键业务结果仍应由上层独立核对。
环境变量
变量 | 作用 |
| 第一次工具调用时就在后台加载本地模型。默认关闭:开启后首个视觉任务快约 1.7–2.6 s,但只做 DOM 的会话会白占约 2.3 GB 显存 |
| 关闭悬浮窗动效 |
| 关闭悬浮窗的半透明亚克力效果,改用不透明深色背景 |
测试
.\.venv\Scripts\python.exe -u .\scripts\test_cua_mcp.py全量回归约 2 分钟,会启动一个隔离的 Chrome 和本地模型,覆盖 Stdio / HTTP 两种 MCP、提交判定、桌面 OCR、前台保护、悬浮窗交互与动效。需要本地模型文件;界面相关的测试会短暂在屏幕上显示窗口。
模型训练
本地模型是 Qwen/Qwen3.5-2B 的 LoRA 微调(语言侧,监督微调),合并后导出为 GGUF(Q4_K_M)和配套的视觉投影文件。当前使用的一版(M3.5)训练集 4,148 条、验证集 645 条,来源是公开网页定位数据、自采的中文 Chrome 截图和困难负样本,在 Colab A100 上训练。输出是单行 JSON 动作(left_click、type、scroll、not_found 等,坐标 0–1000 归一化)。
01_任务书_Chrome视觉鼠标操作模型.md:最初的工程任务书(动作空间、坐标与 DPI 链路、数据规范、验收标准)。项目后来从“纯视觉模型”转向“DOM 优先、模型兜底”,任务书保留作为背景。
02_从YOLO到VLM后训练实战指南.md、03_LLM与VLM训练全景教学手册.md:写给有目标检测经验的人的 VLM 微调入门。
notebooks/:数据准备和 Colab 训练、导出用的 Notebook;由
scripts/build_colab_notebooks.py、scripts/m3_train_colab.py、scripts/m35_build_notebook.py生成。scripts/m1_*、m3_*、m35_*:采集、数据整理、离线对照和端到端评测脚本。训练数据包和评测原始结果不在仓库里。
目录
scripts/cua_engine.py 引擎:托管 / 桌面两条路径、本地模型生命周期、提交判定、保护规则
scripts/chrome_cua_mcp.py MCP 服务(Stdio 与 Streamable HTTP)
scripts/chrome_pilot_panel.py 悬浮窗
scripts/live_chrome_pilot.py 悬浮窗入口与 llama-server 启动
scripts/desktop_perceiver.py 桌面模式的 OCR 与画面感知
scripts/action_executor.py 带保护的真实键鼠执行
scripts/test_cua_mcp.py 全量回归
scripts/record_demo.py 录制上面的演示动图
configs/ MCP 接入配置示例
notebooks/ 训练与数据准备models/、tools/、artifacts/、profiles/ 是本机生成的目录,不入库。
许可证
代码以 Apache-2.0 发布,见 LICENSE。Qwen3.5 基座模型和 llama.cpp 各有自己的许可证,使用前请分别查看。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Real Chrome for coding agents over MCP: browse, replay playbooks, human takeover, HIPAA & BAA.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables local Chrome control for AI clients over MCP stdio, HTTP, or CLI, exposing 20 tools to extract page text, number and click elements, type text, scroll, manage tabs, capture screenshots, and bind uploaded files to file inputs. Operations run entirely on the local machine with origin allowlists and refusal of untrusted URLs, without calling a cloud model or consuming model tokens.MIT
- AlicenseBqualityBmaintenanceEnables AI agents to control your installed Google Chrome through MCP or HTTP using compact text snapshots, exact pixel coordinates, and a visible cursor. It provides browser tools for navigation, clicking, typing, scrolling, tabs, forms, waiting, recording, and human handoff.3597 npm3MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control Chrome tabs or headless Chrome through a local API or MCP interface, batching browser actions and enforcing user-defined security restrictions.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to automate a user-owned local Chrome browser or personal Linux host by opening pages, reading controls, clicking, filling forms, extracting information, taking screenshots, and saving encrypted profiles, while pausing for brief human handoff during logins, CAPTCHAs, 2FA, or OAuth approval.1-