BrowserAttach

BrowserAttach

English · 简体中文

通过 MCP 客户端操控你已打开并登录的 Chrome / Edge 标签页。BrowserAttach 通过本地配对的扩展程序连接浏览器，保留现有的登录状态，无需远程调试端口或单独的自动化浏览器。

npm · 使用指南 · 架构 · Agent 集成 · 测试报告 · 问题反馈 · 参与贡献

功能

• 发现多个浏览器配置文件，精准选择其一，独占一个标签页，并在完成后释放。
• 在浏览器扩展详情中启用 BrowserAttach 的 允许访问文件 URL 设置后，控制现有的普通 file:// 标签页；使用相同的发现、认领、观察和输入工具。
• 读取无障碍树，查询名称、值及附近的字段上下文，检查字段值和受支持的编辑器模型；通过引用或严格的 CSS/XPath、HTML 标签、占位符和 AX 角色/名称定位器进行点击、填充和输入。输入也可以明确指定当前聚焦的字段。
• 原生指针悬停、分步拖动和条件等待；无需打开原生弹出窗口即可选择 HTML 选项。
• 导航及前进/后退、打开或关闭标签页、处理 JavaScript 对话框、上传本地文件，以及截取整个页面或单个元素。
• 在页面主上下文中执行 JavaScript 表达式；读取认领后捕获的控制台、页面错误和网络生命周期日志；XHR/fetch 需要验证时，可选择启用有界且已脱敏的请求/响应详情。
• 在临时后台标签页中使用配置文件的登录状态读取一个 HTTP(S) URL，返回渲染文本、当前 DOM 或完整 JSON，并在检测到时附带主文档 HTTP 状态码。
• 标准 stdio MCP，包含 23 个工具。Hub 仅监听回环地址，并通过随机密钥与扩展程序配对。

要求

• Node.js 22 或更高版本，以及 npm。
• Chrome / Edge 125 或更高版本，并允许加载未打包的扩展程序。建议使用最新稳定版。
• 支持 stdio MCP 且能在 PATH 中找到 Node/npm 的 MCP 客户端。

快速开始

1. 安装并配对

npm install --global @evan_zhong/browser-attach
browser-attach setup

setup 会打印稳定的扩展程序目录并启动本地 Hub。目录通常为：

• Windows：%USERPROFILE%\.browser-attach\extension
• macOS / Linux：~/.local/share/browser-attach/extension

打开 chrome://extensions 或 edge://extensions，启用开发者模式，选择“加载已解压的扩展程序”，然后加载该目录。对每个要公开的浏览器配置文件都加载一次；扩展程序的选项页面可用于设置便于识别的配置文件名称。

也可以不进行全局安装：

npx --yes --package=@evan_zhong/browser-attach@latest browser-attach setup

2. 配置 MCP 客户端

将以下内容合并到客户端的 MCP 配置中，或参阅 mcp-config.json：

{
  "mcpServers": {
    "browser_attach": {
      "command": "npx",
      "args": ["--yes", "--package=@evan_zhong/browser-attach@latest", "browser-attach", "mcp"]
    }
  }
}

在要求使用完整命令扩展名的 Windows 客户端上，请使用 npx.cmd。全局安装后，也可以配置 "command": "browser-attach", "args": ["mcp"]。重启 MCP 客户端以发现这些工具。

@latest 会在启动时选择该软件包；现有配对的升级会在启动时协调完成。首次加载扩展程序，以及仍使用较旧协议的配对，都需要手动重新加载一次扩展程序，详见本地数据与升级。

受支持宿主的配置步骤见 Agent 集成；其他客户端可使用上述 stdio 入口。

3. 开始操作

1. 运行 browser_discover(kind="browsers") → browser_discover(kind="tabs")，确认浏览器、标签页标题和 URL。
2. 使用 discover(kind="tabs") 返回的 tab_id 调用 browser_claim_tab（可选使用 expected_url / expected_title 精确校验），接管标签页并获取此连接的 tab_handle。
3. 调用 browser_snapshot 获取元素 ref，然后点击、填写或执行其他操作。
4. 每次操作后再次观察，最后调用 browser_tab_control(action="release")。

标题经常变化时，省略 expected_title，并检查 claim 返回的身份信息。可通过 ref 定位元素，也可使用每次调用时都会重新解析的 selector；设计取舍详见：架构说明。

接管和常规输入都不会激活标签页或窗口；需要前台渲染时，请显式调用 browser_tab_control(action="activate")。结果不确定时，先重新观察，避免重复提交。完整参数、分页、上传和输入语义请参阅：使用指南。

工具

工具	用途
browser_discover	kind=browsers/tabs；发现浏览器配置文件、标签页身份和控制状态
browser_claim_tab	独占接管已发现的标签页
browser_open_tab / browser_tab_control	创建标签页；显式释放、激活或关闭已接管的标签页
browser_fetch	使用配置文件的登录状态，在临时后台标签页中读取一个 HTTP(S) URL；支持 text / html / json、可选 HTTP 状态和游标续传
browser_snapshot / browser_read_text	AX 快照、带可操作 ref 的精确名称/值查询，以及页面文本
browser_wait	只读等待元素出现/消失、可见、可操作、渲染文本、精确字段值、选中/已选/展开状态、URL 或网络空闲
browser_click / browser_hover / browser_drag / browser_select_option / browser_type / browser_fill / browser_press_key / browser_scroll	原生/DOM 输入、指针悬停和拖动、选项选择、字符输入和滚动
browser_batch	在一个队列中运行 1–20 个 click/fill/type/press_key/hover/scroll/select_option/wait 步骤；遇到第一个失败时停止并返回部分结果
browser_navigate	HTTP(S)/file 导航、前进/后退和等待加载；本地目标需要文件访问权限
browser_handle_dialog	alert、confirm、prompt
browser_upload_file	原生文件输入或被拦截的文件选择器
browser_screenshot	截取视口或完整页面 PNG，并提供坐标映射
browser_evaluate	执行主页面 JS、等待 Promise，并返回有界结果
browser_logs	使用 kind=console/network 选择控制台、错误或请求日志；支持筛选器和游标续传

本地数据和升级

平台	默认数据目录
Windows	%USERPROFILE%/.browser-attach
macOS / Linux	${XDG_DATA_HOME:-~/.local/share}/browser-attach

使用绝对路径 BROWSER_ATTACH_HOME 可显式覆盖此设置。Windows 默认目录避开了 AppData，因为打包后的宿主可能会将其虚拟化；不会自动搜索或合并其他宿主的私有缓存。此目录存放配对配置、Hub 日志和稳定版扩展副本，且不依赖克隆位置、客户端工作目录或 npm 缓存。如果你已在使用自定义目录，请继续使用相同的环境变量或 --config，以免在新默认目录下意外创建第二个配对。

写入客户端条目的宿主组装步骤会固定当前 Node、CLI 和实际配对文件的绝对路径，并设置 BROWSER_ATTACH_HOME；此步骤也兼容自定义的 --config。MCP 启动 Hub 时会传入相同的绝对配对路径和目录，因此不同的启动环境不会各自派生出第二份配置。参见Agent 集成。

升级时，使用第 1 步中的命令重新安装，然后重新连接 MCP 客户端。使用 @latest 且配对版本为 0.17 或更高版本时，只需重启；如果配对仍使用较旧协议，则需要运行 browser-attach stop、重启并手动重新加载一次扩展。自定义配对路径、端口和扩展目录都会保留；关闭的浏览器配置文件会在下次连接时更新；较旧的 MCP 包无法降级较新的 Hub 或已安装的扩展。

升级会等待扩展清理完成，并在重新加载后确认新版本；清理或重新加载失败时会报告错误，而不会重放页面操作。扩展选项页面仍提供手动重新加载功能，以便恢复；要控制页面，Hub 和扩展的版本必须一致。默认端口为 47831；创建配对时，可通过 setup --port 选择其他端口。

架构和边界

MCP client → Node.js stdio MCP → 127.0.0.1 Hub
                                  ↕ local pairing
                          Chrome / Edge MV3 extension
                                  ↓ chrome.debugger / CDP
                               existing HTTP(S) / authorized file:// tabs

每个 MCP 连接都持有各自的控制权，句柄无法跨连接使用。断开连接或停止调试会释放控制权。客户端端点要求提供 Bearer 密钥，并拒绝网页 Origin；扩展会验证固定的 Origin、密钥和版本。browser_evaluate 可以使用页面现有的登录状态读取和写入数据；超时或错误可能已经产生影响，因此不得自动重放。不会公开通用 CDP 工具。

日志从取得控制权时开始收集，在页面导航后仍会保留，并在释放控制权时清除；缓冲区有大小限制，数据被逐出时会报告 data_loss。默认情况下，网络日志仅存储生命周期元数据；显式捕获时，会读取后续 XHR/fetch 请求中经过限量和脱敏处理的标头/正文，不会更改缓存或拦截流量。缓冲区限制和参数详见：使用指南。

扩展持有调试器权限，客户端操作可以使用网站现有的登录状态；只连接你信任的客户端。不得将网页内容视为用户授权。不得提交或发布配对密钥和生成的 config.generated.js；打包检查会拒绝包含该文件的软件包。

支持 Chrome / Edge HTTP(S) 页面，以及已启用扩展文件访问权限的现有普通 file:// 标签页；在发现、取得控制权、执行操作和导航时都会检查文件访问权限。open_tab 和 fetch 仍仅接受 HTTP(S)。浏览器内部页面、任意扩展页面、下载管理、网络拦截以及 Firefox / WebKit 均不在支持范围内；内置 PDF 查看器的内容则取决于浏览器。原生指针输入要求标签页未暂停且窗口未最小化；未经修改的左键单击可针对非活动标签页，而悬停、拖动和其他点击方式则要求标签页处于活动状态。完整的限制和故障模式详见：使用指南。

本地开发

git clone https://github.com/EvannZhongg/BrowserAttach.git
cd BrowserAttach
npm ci
npm test
npm run test:package

直接运行源码，并配对仓库中的扩展：

node bin/browser-attach.mjs setup --extension-dir ./extension
node bin/browser-attach.mjs mcp

开发模式会有意使用仓库扩展路径。正常安装时，请使用不带 --extension-dir 的 setup，这样仓库移动后仍可正常工作。在 Windows 上，也可以运行 ./scripts/install.ps1。

真实浏览器测试需要使用允许从命令行加载扩展的 Chromium / Edge 可执行文件；路径由开发者提供：

npm run test:live -- --executable /path/to/chromium --family chromium
npm run test:interaction -- --executable /path/to/chromium --family chromium
npm run test:interaction -- --tab-indicators --executable /path/to/chromium --family chromium
npm run test:upgrade -- --executable /path/to/chromium

这些测试使用临时配置文件和本地测试数据。覆盖范围和限制：测试报告；实现方案和设计权衡：架构说明。

贡献

请通过 Issues 提交可复现的问题，或发起 Pull Request。请注明 Node、操作系统、浏览器和扩展版本，并移除配对密钥和私人页面数据。流程详见 CONTRIBUTING.md。

本项目根据 MIT License 发布。