Hermes Chrome Bridge

让 Hermes 像 Codex Desktop 一样，安静地控制你正在使用的真实 Chrome：

• 沿用现有 Chrome 登录态、Cookies 和标签页

• 不抢鼠标、不抢键盘、不把窗口切到前台

• 不依赖每次都要确认的 DevTools autoConnect 调试弹窗

• 每个活跃 Hermes 任务使用不重复颜色的 Chrome 标签组

• 后台桥接由 launchd 常驻，Hermes 重启后仍可继续使用

本项目基于 MIT 许可的 agent-browser-mcp 扩展而来，增加了 Hermes 任务绑定、彩色标签组、常驻服务和可复用安装方案。

它解决什么问题

官方 Chrome DevTools 自动连接会显示“允许调试”确认，这是 Chrome 的安全边界， 并不适合无人值守任务。桌面鼠标自动化虽然不需要这个确认，却会抢占用户输入， 也难以并发。

Hermes Chrome Bridge 改用一次性人工安装的本地 Chrome 扩展作为信任边界。 扩展通过 loopback WebSocket/HTTP 桥与 MCP 服务通信，使用 Chrome API 和 CDP 在后台操作页面。Hermes 的当前 task_id 会在每次浏览器调用前自动绑定，因此 不同任务不会混用标签页，并会显示为不同颜色的标签组。

Related MCP server: Real Browser MCP

效果

Hermes 任务 A ── 蓝色标签组 ── 后台操作真实 Chrome
Hermes 任务 B ── 粉色标签组 ── 后台操作真实 Chrome
你本人        ── 普通标签页 ── 鼠标键盘不受影响

同一个任务在不同 Chrome 窗口中会创建同名、同色的标签组。新标签默认在后台 打开；接管已有标签时会将其归入当前任务组。

系统要求

• macOS

• Google Chrome

• Python 3.10+

• 本地源码安装的 Hermes Agent

• Hermes Python 环境通常位于 ~/.hermes/hermes-agent/venv

核心 MCP 服务也可用于 Claude Desktop、Cursor 等客户端；自动 task_id 绑定和 launchd 安装脚本目前针对 Hermes/macOS。

快速安装

git clone https://github.com/linsipeng/hermes-chrome-bridge.git
cd hermes-chrome-bridge
bash scripts/install-hermes-macos.sh

安装器会：

1. 把当前仓库以 editable 模式装入 Hermes Python 环境；

2. 尝试给 Hermes MCP 调度器应用任务绑定补丁；

3. 安装并启动 com.hermes.chrome-bridge LaunchAgent。

如果 Hermes 不在默认目录：

HERMES_SOURCE=/path/to/hermes-agent \
PYTHON=/path/to/hermes/venv/bin/python \
bash scripts/install-hermes-macos.sh

一次性加载 Chrome 扩展

执行：

~/.hermes/hermes-agent/venv/bin/agent-browser-mcp extension-path

然后：

1. 打开 chrome://extensions

2. 开启“开发者模式”

3. 点击“加载已解压的扩展程序”

4. 选择上面命令输出的目录

5. 打开任意正常的 http:// 或 https:// 页面

这是一次性的显式授权。之后不需要每次点击“允许调试”。

Hermes 配置

把 examples/hermes-config.yaml 合并进 ~/.hermes/config.yaml：

mcp_servers:
  agent_browser:
    command: /absolute/path/to/agent-browser-mcp
    session_binding_tool: bind_hermes_session
    timeout: 120
    connect_timeout: 60
    tools:
      exclude:
        - capture_desktop_screenshot
        - mouse_move
        - mouse_click
        - mouse_drag
        - type_text
        - hotkey
        - pointer_info

建议排除物理输入工具，让 Hermes 默认只使用后台 DOM/CDP/Chrome API 控制。

重启并验证：

hermes gateway restart
hermes mcp test agent_browser
agent-browser-mcp doctor

主要 MCP 工具

• bind_hermes_session：绑定 Hermes 任务和标签组

• list_tabs：查看真实标签页及任务归属

• switch_tab：接管已有标签并加入当前任务组

• open_new_tab：后台打开并自动分组

• release_hermes_session：释放标签组，可选择关闭组内标签

• scan_page：读取简化后的页面内容

• execute_js：在真实页面执行 JavaScript

• cdp_command / cdp_batch：调用 Chrome DevTools Protocol

• get_cookies：读取当前真实 Chrome 会话 Cookies

• capture_page_screenshot：后台页面截图

服务管理

launchctl print gui/$(id -u)/com.hermes.chrome-bridge
agent-browser-mcp doctor
hermes mcp test agent_browser

卸载常驻桥：

bash scripts/uninstall-hermes-macos.sh

卸载脚本不会自动撤销 Hermes 源码补丁，以免覆盖用户的其他本地修改。

架构与经验

• 架构说明

• 这次实现沉淀的经验

• Hermes 自动会话绑定补丁

安全说明

这个扩展能控制你的真实 Chrome，因此需要 cookies、debugger、tabs 和 <all_urls> 等高权限。请只安装你审查过的源码，不要安装来源不明的二次打包版本。

桥接服务只监听 127.0.0.1:18765/18766。不要把这些端口转发到局域网或公网。 项目不会上传 Cookies；但任何能在本机调用该 MCP 的程序，都可能获得浏览器操作能力。

已知限制

• chrome:// 等 Chrome 内部页面无法被普通扩展脚本控制。

• Chrome 扩展仍需用户首次手动加载，这是有意保留的安全授权步骤。

• Hermes 上游升级可能导致补丁上下文变化；安装器会停止并提示手动处理，不会强改。

• Windows/Linux 可以运行 MCP 和扩展桥，但常驻服务安装脚本尚未提供。

致谢

底层 TMWebDriver、页面简化和扩展桥来自 335234131/agent-browser-mcp， 原项目使用 MIT License。本仓库保留相同许可证。

License

MIT