agent-webbridge

WebBridge（Agent WebBridge）

WebBridge（agent-webbridge）：使用 Claude Code、Cursor 和任何 MCP 客户端操控你已登录的真实 Chrome——支持多个 Chrome 配置文件，并实现真正的逐标签页 DevTools 并行处理。100% 开源（MIT），零云端服务，无遥测，全部运行在 127.0.0.1 上。

🌐 交互式网站和演示录屏：jeet-dhandha.github.io/agent-webbridge

将其添加到你的 Agent（30 秒）

npm i -g agent-webbridge && awb setup "Work"     # once: installs the daemon + the Chrome extension

然后将 MCP 服务添加到 Claude Desktop、Claude Code、Cursor 或 Windsurf：

{
  "mcpServers": {
    "chrome": { "command": "npx", "args": ["-y", "agent-webbridge", "mcp"] }
  }
}

Claude Code：claude mcp add chrome -- npx -y agent-webbridge mcp

或者将其安装为 Agent 技能（适用于 Claude Code、Cursor、Codex 等）：npx skills add jeet-dhandha/agent-webbridge

现在，你的 Agent 可以使用 browser_navigate、browser_snapshot、browser_click、browser_fill、browser_evaluate、browser_screenshot 等工具——所有操作都在你的 Chrome 中运行，使用你的会话。传入 profile 选择账号，传入 tabId 并行操作多个标签页。如果调用失败，browser_status 会告知 Agent 哪个配置文件尚未连接。

为什么不选 Playwright 或云端浏览器？

	云端浏览器（Browserbase、Steel…）	无头 Playwright / Puppeteer	agent-webbridge
费用	按使用量计费	免费	免费，MIT
你的登录状态、通行密钥、双重身份验证	重新验证身份或上传 Cookie	重新登录；双重身份验证会失效	已登录
浏览器身份	云端和数据中心 IP 经常受到挑战	无头浏览器经常受到挑战	你自己的 Chrome 配置文件（网站仍可能限制自动化操作）
数据去向	第三方服务	本地	仅本地，127.0.0.1
同时使用多个账号	需要管理独立会话	手动编排	每个账号一个配置文件，可并行操作多个标签页

它会自动化操作你已登录的浏览器——仅将其用于你有权自动化操作的账号和网站，并遵守各网站的条款。

agent-webbridge 是一个轻量级 Node 守护进程（仅一个运行时依赖：ws），以及一个全新开发的 MV3 Chrome 扩展。Agent 向本地路由器 POST 一条命令 → 路由器将命令转发给相应配置文件的守护进程 → 扩展按标签页连接 Chrome DevTools 协议。

查看实际效果

真实运行，而非演示模型：脚本向 npx agent-webbridge mcp 发送 MCP 调用，由它操控一个真实且已登录的 Chrome 配置文件。截图来自浏览器本身，耗时也经过实测。仅访问公开页面；不会向任何账号提交内容。

阅读任意页面：在 Hacker News 上执行快照和 evaluate	同时操作五个标签页：并行耗时 3.5 秒，逐个操作耗时 9.3 秒
使用你的真实登录状态：填写已登录的编辑器，在发布前停止	填写并提交表单（字段、单选按钮、复选框）

耗时数据来自一台使用家庭宽带的 MacBook；你的结果可能有所不同。

概述

• 操控真实浏览器 — 使用你实际的 Chrome 和登录会话。无需在无头模式下重新登录，也无需绕过身份验证抓取内容。
• 并行运行多个标签页 — 扩展会为每个标签页附加 chrome.debugger，因此同一配置文件中的 N 个标签页可以并发运行。在我们的基准测试中，5 个标签页并行耗时 3.5 秒，而逐个运行耗时 9.3 秒（测试设备为一台 MacBook；你的结果可能不同）。
• 跨多个配置文件运行 — 每个配置文件运行一个守护进程。总并发量 = 配置文件数 × 标签页数，全部通过一个端点访问。
• 保持隐私 — 使用自己的守护进程和 MV3 扩展，无闭源依赖，也无需账号。所有操作都在本地完成。

安装

npm i -g agent-webbridge        # 1. the daemon + the `awb` CLI
awb setup "Work"                # 2. opens the Chrome Web Store; click "Add to Chrome"

awb setup 会在你选择的配置文件中打开 Agent WebBridge 列表页，并在你点击 添加至 Chrome 时持续轮询。一旦检测到安装完成，它就会将该配置文件连接到对应的守护进程，并启动整个集群。

要求： macOS 或 Windows · Google Chrome · Node.js ≥ 18。

快速开始

awb up "Work" "Personal"        # bring profiles up (setup did this on first run)

# Drive any profile by name — using the handy cmd helper function:
cmd(){ curl -s -m 60 -X POST http://127.0.0.1:10086/command -H 'Content-Type: application/json' -d "$1"; echo; }

cmd '{"action":"navigate","args":{"url":"https://news.ycombinator.com"},"session":"scan","profile":"Work"}'

awb down                        # stop the fleet when done

每次调用都会向 127.0.0.1:10086 发送 POST /command 请求。请将负载用单引号（'...'）括起来，以避免 shell 引号转义问题。"session" 会将某个任务的标签页归入同一个 Chrome 标签组；"profile" 用于选择要操控的 Chrome 配置文件。传入 {"action":"screenshot","args":{"path":"/path/to/img.png"}} 可将屏幕截图直接保存到磁盘。

工具（15 个原生工具 + 状态）

工具	功能
navigate	在新标签页或现有标签页中打开 URL
find_tab	按 URL / 标题查找标签页
evaluate	在页面中运行 JavaScript 并返回结果
snapshot	获取包含稳定 @e 元素引用的无障碍树
click	根据 @e 引用点击元素（合成 DOM 点击）
trusted_click	执行真实鼠标点击（CDP，isTrusted），适用于忽略 click 的页面
fill	设置原生输入框和 contenteditable 富文本字段
upload	以编程方式将文件指定给 <input type="file">
file_chooser_intercept	在以编程方式上传文件时，拦截原生操作系统文件选择器对话框（Finder/Explorer）
screenshot	将整页或元素截图直接保存到磁盘
save_as_pdf	将页面保存为 PDF
network	捕获网络请求（start、stop、list、detail）
list_tabs	列出打开的标签页及其 ID 和标签组信息
close_tab	关闭标签页
close_session	关闭会话及其整个标签组

编程 SDK（Node.js 和 Python）

Node.js ESM SDK

import { WebBridgeClient } from "agent-webbridge";

const client = new WebBridgeClient({ profile: "Work", session: "my-task" });
await client.navigate("https://example.com");
const title = await client.evaluate("document.title");
console.log("Title:", title);

Python 3 SDK（零依赖）

from scripts.awb_client import WebBridgeClient

client = WebBridgeClient(profile="Work", session="my-task")
client.navigate("https://example.com")
title = client.evaluate("document.title")
print("Title:", title)

工作原理

  AI agent  ──HTTP POST /command──▶  router (127.0.0.1:10086)   routes by "profile"
                                          │
                       ┌──────────────────┼──────────────────┐
                       ▼                  ▼                  ▼
                  daemon "Work"      daemon "Personal"     daemon …      one per profile
                       │  WebSocket
                       ▼
                  MV3 extension      ──chrome.debugger (a Map: one attach PER TAB)──▶
                       │
                       ▼
                  Chrome DevTools Protocol      tab 1 ║ tab 2 ║ tab 3   (concurrent)

路由器会将每条命令代理到对应配置文件的守护进程，该守护进程使用确定性哈希端口；守护进程通过 WebSocket 将命令中继到该配置文件的扩展；扩展会维护一个 Map，记录 chrome.debugger 附加状态，每个标签页对应一条，并发出 CDP 调用。每个标签页各自维护映射正是关键所在：将所有操作都导向单个“当前标签页”的桥接程序，每个配置文件只能操控一个标签页；而这种方式可以操控 N 个标签页。

CLI

命令	作用
awb setup <profile…>	一次性安装：引导完成“加载已解压的扩展程序”、连接并启动整个集群
awb up <profile…>	启动指定配置的守护进程和路由器，打开窗口并连接
awb down	停止路由器和整个集群
awb connect <profile…> [--no-restart]	将各配置的扩展指向其守护进程。如果扩展已是最新版本，Chrome 会保持打开；--no-restart 绝不会关闭 Chrome（否则会失败）
awb check [profile…] [--json]	只读就绪探测（目录是否存在？是否启用开发者模式？是否已加载？是否已连接？）——Agent 在安装期间会轮询此命令
awb status	查看各配置的守护进程和扩展连接状态
awb doctor	诊断环境（Chrome、配置、守护进程、扩展）
awb mcp	运行 stdio MCP 服务（上述配置启动的内容）
awb profiles	列出 Chrome 配置、其哈希端口以及扩展是否存在

<profile> 可以是任何能唯一解析的值——配置的名称（"Work"）、电子邮件地址或 Chrome 目录（"Profile 2"）。

在 AI Agent 中使用

将其作为 Claude Code 技能 / 插件提供——捆绑的 agent-webbridge 技能会教 Agent 完整流程（通过 awb check --json 安装，然后通过 POST /command 操作）。要改进扩展本身，可运行 awb install-dev，从仓库内的构建加载已解压的扩展程序（chrome://extensions → 开发者模式 → 加载已解压的扩展程序 → agent-webbridge-extension/）；它自带密钥，因此开发版 ID 在重新加载后保持不变。

社区配方（awb-recipes）

网站会不断更新标记语言并部署反机器人陷阱。与其让 Agent 猜测选择器或在边缘情况下失败，不如浏览社区维护并验证过的操作手册：awb-recipes。

• github-gist-create：通过浏览器界面和当前会话创建私密或公开的 GitHub Gist。
• google-search-results：从你已登录的浏览器中提取自然搜索结果。
• hn-reply-box：使用真实用户 Cookie 与 Hacker News 讨论串交互。
• linkedin-feed-posts：提取真实动态内容，不劫持会话。
• npm-most-depended：提取软件包下载指标和依赖层级。

将配方交给 Agent：“用我的 Work 配置执行 awb-recipes 中的 github-gist-create 配方。” 要参与贡献，请认领一个带有 good first recipe 标签的未解决问题并提交 PR！

生态与收录

• 官方 MCP Registry：已注册为 io.github.jeet-dhandha/agent-webbridge（注册表目前显示 1.3.1）
• Awesome MCP Servers：已向 punkpeye/awesome-mcp-servers 提交 PR（正在等待 Glama 收录）
• Awesome Claude Skills：已向 BehiSecc/awesome-claude-skills、karanb192/awesome-claude-skills 和 travisvn/awesome-claude-skills 提交 PR
• Skills CLI：可通过 npx skills add jeet-dhandha/agent-webbridge 安装
• Chrome Web Store：已发布扩展 Agent WebBridge
• 网站与互动演示：jeet-dhandha.github.io/agent-webbridge

平台

	macOS	Windows
配置文件发现	~/Library/Application Support/Google/Chrome	%LOCALAPPDATA%\Google\Chrome\User Data
Chrome 二进制文件	/Applications/Google Chrome.app	Program Files\Google\Chrome\Application\chrome.exe（自动检测）
守护进程、路由器、MCP、所有工具	✅	✅
安装流程（awb setup）	通过 AppleScript 打开配置文件窗口	启动带有该配置文件的 Chrome 来打开
标签页／窗口整理（聚焦、整理空白窗口）	✅	跳过——仅影响外观

如果 Chrome 或其数据目录位于非标准位置（例如 Chrome Beta、便携版安装），请设置 AWB_CHROME_BIN / AWB_CHROME_DIR。Linux 路径已配置，但未经测试。

在 Windows 上，请从 PowerShell 或 cmd 运行命令（下方的 curl 示例使用 bash 引号；在 PowerShell 中请使用 curl.exe 和 here-string，或者直接使用 MCP 服务）。守护进程和 Windows 代码路径已由 windows-latest 上的 CI 覆盖；启动 Chrome 的步骤（awb setup / awb up）测试最少——如果出现异常，请提交 issue。

安全

• 所有服务仅监听 127.0.0.1。从 1.3.1 版起，路由器和守护进程也会拒绝携带 Web Origin 或非环回 Host 的请求，因此你访问的网站无法操控该桥接服务（请参阅更新日志）。请从早期版本升级，并通过 awb down && awb up 重启所有服务。
• 它会以你的身份在已登录的浏览器中操作。任何能够访问 127.0.0.1:10086 的本地程序都能执行相同操作，因此请仅在你信任的机器和账户上运行，并在 Agent 中为不可逆操作（发帖、付款、删除）设置人工确认。
• 请通过 GitHub 的 Security 选项卡中的“Report a vulnerability”私下报告漏洞。

许可证

MIT © jeet-dhandha