How do I use aa-browser?

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.

aa-browser

by yuchen0x1

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Aa Browser

为 AI Agent 而生的开源桌面浏览器。

License Platform MCP

人像人一样浏览网页，Agent 像工程师一样驱动它。 The Agent-Native Browser — snapshots, actions, and packet capture over MCP.

传统浏览器是为"人眼看像素"设计的；而 AI Agent 需要的是结构化页面数据。Aa Browser 是一个完整的 Chromium 浏览器，任何人都可以正常使用它上网；同时，任何支持 MCP（Model Context Protocol）的 AI Agent 都可以连接进来，读取页面的结构化快照（可访问性树 + 元素 ref 编号），并执行点击、输入、选择、滚动、提取等操作——不看截图、不猜坐标。

特性

🖥️ 真浏览器：基于 Electron（Chromium），标签页 / 地址栏 / 前进后退 / 登录态持久化，一应俱全
🧠 结构化快照：页面被转换成 YAML 风格的可访问性树，每个可交互元素带 ref 编号（- button "登录" [ref=e5]），格式对齐 Playwright MCP 生态，Agent 零学习成本
💸 增量快照省 token：页面没变 → 一行回复；小变化 → 只返回变更区块；ref 跨快照稳定复用（React 重渲染也能靠内容签名接上）；跳转/大变化自动回退完整快照。一次多步任务可省 60%+ 上下文
🤖 MCP 原生接入：标准 stdio MCP 桥，ZCode / Claude Code / Cursor 等任何 MCP 客户端均可驱动
🔒 本地安全：WebSocket 仅监听 127.0.0.1，随机端口 + 一次性 token，拒绝非本机连接
🎯 真实输入路径：点击走受信任的输入事件（isTrusted=true），输入走 insertText 管线并对 React 受控组件兜底，被遮挡元素自动降级为合成事件
🔁 动作后自动快照：每次点击/输入后自动返回新快照，Agent 无需二次请求即可继续决策

Related MCP server: project-tendril

快照示例

在必应首页调用 browser_snapshot 得到：

页面快照 url: https://www.bing.com/
title: 搜索 - Microsoft 必应
元素数: 19

- banner "登录 Rewards 手机版"
  - img "必应"
  - navigation
    - menuitem "图片" [ref=e1]
    - menuitem "视频" [ref=e3]
- search
  - combobox "搜索网页" [ref=e15]
  - button "语音搜索" [ref=e16]

Agent 随后：

{ "tool": "browser_type",   "arguments": { "ref": "e15", "text": "Aa Browser", "submit": true } }

点击/输入后自动返回的是增量快照——只有变化的区块：

页面快照（增量） url: https://www.bing.com/search?q=Aa+Browser
title: Aa Browser - 搜索
变化: +6 / -1（共 214 行，其余未变，仍以上次快照为准）

  - search
+ - link "agent-browser.dev" [ref=e37]
+ - text "Browser automation for AI agents …"
- - text "（旧的空白提示）"

新增 ref: e37 e38
失效 ref: e12

页面未变化时只回一行（≈50 token）；跳转到新页面或变化过大时自动回退完整快照。browser_snapshot { full: true } 可强制完整树。

架构

┌─────────────────────────────────────────────────────┐
│                Aa Browser (Electron)                │
│  ┌───────────────────────────────────────────────┐  │
│  │  外壳 UI（标签栏/地址栏） ←→ 主进程 IPC        │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │  页面标签 WebContentsView × N                 │  │
│  │    └─ 注入快照引擎（DOM → YAML 树 + ref 表）  │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │  Agent 服务 ws://127.0.0.1:<random>           │  │
│  │    ~/.aabrowser/connection.json (port+token)  │  │
│  └───────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────┘
                           │ 本地 WebSocket（token 鉴权）
┌──────────────────────────┴──────────────────────────┐
│  cli/mcp.mjs —— stdio MCP 桥（零依赖）              │
│    任何 MCP 客户端：ZCode / Claude Code / Cursor …  │
└─────────────────────────────────────────────────────┘

快速开始

⚡ 复制粘贴给 AI，全自动安装接入（推荐给 AI 客户端用户）

把 PROMPT.md 里的提示词整段复制给你的 AI 客户端（ZCode / Claude Code / Cursor…），AI 会自动完成下载 → 安装 → 启动 → 写入你本机的 MCP 配置。

不用 AI 的话，等价的手动命令（先拿到 install.mjs 与安装包）：

node install.mjs --url  <安装包直链或本地路径>     # 下载/安装/启动/接入一条龙
node install.mjs --repo yuchen0x1/aa-browser            # 自动拉 GitHub Releases 最新版
node install.mjs --url <...> --clients zcode,cursor   # 只接入指定客户端

需要先把安装包发布到可公开下载的位置（GitHub Releases / 网盘直链），步骤见 PROMPT.md 末尾"给发布者"。

其他方式

要求：Node.js ≥ 20，Windows / macOS / Linux。

方式一：Windows 安装包（推荐给普通用户）

npm run dist       # 产出 release/Aa Browser-Setup-<版本>.exe（NSIS 安装器）

双击安装（未做代码签名，Windows SmartScreen 会提示"更多信息 → 仍要运行"）。装好后打开 Aa Browser，新标签页上有**「一键接入你的 AI 客户端」**卡片，勾选客户端点一下即完成 MCP 配置。

方式二：源码运行（开发者）

git clone https://github.com/yuchen0x1/aa-browser.git aa-browser
cd aa-browser
npm install        # 首次会下载 Electron，慢可设镜像：
                   # export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm run build      # 构建主进程 / 预加载 / 渲染层
npm start          # 启动 Aa Browser

开发模式（热更新渲染层）：

npm run dev

接入你的 Agent

方式 A · 一键接入（推荐）：Aa Browser 新标签页 → 「一键接入你的 AI 客户端」卡片 → 勾选 → 写入。命令行等效：node cli/setup.mjs --yes（--list 查看，--client zcode,cursor 指定目标）。支持：ZCode / Claude Code / Cursor / Windsurf / Cline / VS Code / Gemini CLI / Qwen Code。写入前自动备份原配置为 <file>.aa-backup-<时间戳>，幂等可重复执行。

方式 B · 手动配置：在 MCP 客户端配置中添加：

{
  "mcpServers": {
    "aa-browser": {
      "command": "node",
      "args": ["C:\Program Files\aa-browser 或 %LOCALAPPDATA%\Programs\Aa Browser/cli/mcp.mjs"]
    }
  }
}

前提：Aa Browser 保持运行（它会在 ~/.aabrowser/connection.json 写入本地端口与 token，MCP 桥通过它发现浏览器）。

然后让 Agent 干活，例如："用浏览器打开 GitHub trending，把前 10 个项目整理成表格" 或 "打开 xx 后台，把登录后的接口响应都抓给我看"。

MCP 工具

工具	说明
`browser_navigate`	导航到 URL（非 URL 文本自动转搜索词；结果内嵌完整快照，`snapshot: false` 可跳过）
`browser_snapshot`	结构化页面快照（增量模式省 token；`full: true` 强制完整树）
`browser_click`	按 ref 点击（自动返回增量快照）
`browser_type`	按 ref 输入文本（支持 `submit` 回车提交、`clear` 清空）
`browser_select_option`	按 ref 选择下拉项（按 value 或可见文本匹配）
`browser_scroll`	滚动页面（先主文档，后最大滚动区域）
`browser_extract`	提取整页或指定元素的纯文本
`browser_wait`	等待指定文本出现（轮询）
`browser_press_key`	按键：Enter / Escape / 方向键 / 单字符等
`browser_screenshot`	PNG 截图（图像 + 保存路径）
`browser_console`	读取页面控制台日志
`browser_network_requests`	抓包：列出捕获的 HTTP 请求（方法/状态/类型/大小/耗时/URL，支持过滤）
`browser_network_detail`	抓包：单个请求的完整请求/响应头 + 响应体（`body: true`）
`browser_har`	抓包：导出 HAR 1.2 文件（可导入 DevTools/Fiddler 人工分析）
`browser_tabs`	列表 / 新建 / 切换 / 关闭标签页

MCP 工具

工具	说明
`browser_navigate`	导航到 URL（非 URL 文本自动转搜索词；结果内嵌完整快照，`snapshot: false` 可跳过）
`browser_snapshot`	结构化页面快照（增量模式省 token；`full: true` 强制完整树）
`browser_click`	按 ref 点击（自动返回增量快照）
`browser_type`	按 ref 输入文本（支持 `submit` 回车提交、`clear` 清空）
`browser_select_option`	按 ref 选择下拉项（按 value 或可见文本匹配）
`browser_scroll`	滚动页面（先主文档，后最大滚动区域）
`browser_extract`	提取整页或指定元素的纯文本
`browser_wait`	等待指定文本出现（轮询）
`browser_press_key`	按键：Enter / Escape / 方向键 / 单字符等
`browser_screenshot`	PNG 截图（图像 + 保存路径）
`browser_console`	读取页面控制台日志
`browser_tabs`	列表 / 新建 / 切换 / 关闭标签页

安全说明

Agent 服务只监听 127.0.0.1，连接需携带启动时生成的随机 token
token 与端口写在用户目录 ~/.aabrowser/connection.json（仅当前用户可读）
一键接入写入其他客户端配置前自动备份、只改 aa-browser 一个键、幂等可重复
注意：Agent 能看到你登录的页面内容与网络流量。请勿让不可信的 Agent 访问网银、工作邮箱等高敏站点；后续版本将加入"操作确认弹窗"与站点白名单（见 Roadmap）

项目结构

aa-browser/
├── src/
│   ├── main/          # 主进程：窗口 / 标签 / 动作 / 抓包 / Agent 服务 / MCP 工具 / 客户端接入
│   ├── preload/       # 外壳 UI 与新标签页的 IPC 桥
│   ├── renderer/      # 浏览器外壳 UI + 新标签页（一键接入卡片）
│   ├── shared/        # 三方共享的协议类型
│   └── snapshot/      # 注入引擎（DOM → 快照）与动作脚本
├── cli/
│   ├── mcp.mjs        # stdio MCP 桥（零依赖）
│   └── setup.mjs      # 一键接入 CLI（零依赖）
├── scripts/           # 冒烟测试 / 实战测试 / 图标生成
├── electron.vite.config.ts
└── electron-builder.yml

测试

npm run smoke   # 端到端冒烟：启动浏览器 → MCP 驱动 → 断言（含抓包，无外网依赖）
node scripts/live-test.mjs   # 实战示例：MCP 驱动必应搜索全流程

Roadmap

操作确认弹窗：Agent 点击/提交前可选人工确认
站点白名单 / 会话隔离分区
~~快照增量更新与缓存（进一步降 token）~~（v0.2.0 已完成）
~~一键接入各大 AI 客户端 + 网络抓包工具集 + Windows 安装包~~（v0.3.0 已完成）
请求拦截与 Mock（Agent 修改/重放请求）
npm 发布 aa-browser-mcp，支持 npx 一行接入
macOS / Linux 打包分发、代码签名

License

MIT

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

Related MCP Connectors

BrowserHere
app.1ts.browserhere
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Browser Automation Agent Orchestration
1
https://browserhere.1ts.app/mcp
Irmu — Web Data MCP
io.github.polgoide
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browser Automation Web Scraping Agent Orchestration
1
https://app.irmu.com/mcp
Browserless
io.browserless
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Browser Automation Web Scraping Agent Orchestration
118
https://mcp.browserless.io/mcp
sncro A
io.github.scottconfusedgorilla
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser Automation Developer Tools Monitoring
2
https://relay.sncro.net/tools/mcp

Related MCP Servers

Playwright MCP Server
Browser Automation Testing & QA Tools
muhammadraheel-vd
F
license
Not graded
quality
D
maintenance
Enables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.
Updated 4 months ago (2026-06-22 05:51 UTC)
-
project-tendril
Browser Automation Web Scraping Search
gadgethd
A
license
Not graded
quality
A
maintenance
Enables AI agents to operate an isolated local Chromium browser through MCP, with semantic snapshots, ref-based actions, search, research, crawling, and CDP access.
Updated 4 days ago (2026-11-02 05:22 UTC)
Apache 2.0
Playwright MCP Server
Browser Automation Agent Orchestration Web Scraping
tomscoppock
A
license
Not graded
quality
B
maintenance
Enables AI agents and clients to control a real Chromium browser through MCP tool calls, including navigation, clicking, typing, JavaScript evaluation, screenshots, and DOM snapshots. Supports multiple isolated sessions over authenticated HTTP with no disk writes.
Updated 2 months ago (2026-09-08 15:58 UTC)
Apache 2.0
jev-ultrafast-mcp
Browser Automation Agent Orchestration
jiawei686
A
license
A
quality
A
maintenance
Enables AI agents to drive a Chromium browser over MCP, reading pages as a numbered list of controls and performing actions like clicking, filling forms, and asserting page state without screenshots or API keys.
Updated a month ago (2026-09-23 12:26 UTC)
10
61 PyPI
20
MIT

Aa Browser

特性

快照示例

架构

快速开始

⚡ 复制粘贴给 AI，全自动安装接入（推荐给 AI 客户端用户）

其他方式

方式一：Windows 安装包（推荐给普通用户）

方式二：源码运行（开发者）

接入你的 Agent

MCP 工具

MCP 工具

安全说明

项目结构

测试

Roadmap

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Playwright MCP Server

project-tendril

Playwright MCP Server

jev-ultrafast-mcp