内容
# agentic-browser-mcp
一款独立的 **MCP 服务器**，为任何 MCP 客户端（Codex、Claude 等）提供浏览器自动化服务，借助 **Playwright** 实现。通过 Chrome DevTools Protocol 驱动一个真实的、已经登录的 Chrome 浏览器 - 跨代理共享 cookie 和会话。
最初从 [pi 编程代理](https://pi.dev) 的浏览器扩展中提取，现在作为独立服务器，以便 **Codex / pi / 任意 MCP 客户端** 都可以使用同一个浏览器。
## 功能
- **11 种工具**：`browser_session`、`browser_navigate`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_eval`、`browser_storage`、`browser_console`、`browser_wait_human`、`browser_screenshot`、`browser_close`
- **两种会话模式**：
- `real` — 连接到端口 `9222` 上现有的 Chrome 浏览器（重用已登录的配置文件：cookie、会话、2FA）
- `isolated` — 启动具有独立配置文件的持久化上下文（有头/无头）
- **自动启动 Chrome**：如果端口 9222 处于关闭状态，服务器将启动 Chrome 启动器脚本并等待它启动 - 无需手动启动浏览器。
- **稳定的元素定位**：`snapshot` 返回 ARIA 无障碍树（YAML）；`click`/`type` 通过 `role` + `name` 定位 - 无需脆弱的引用层。
- **传输方式**：`stdio`（默认，适用于 Codex 风格的 spawn）和 `http`（无状态可流式传输，`--transport http --port 9223`）。
## 要求
- Node.js ≥ 18
- 安装支持 Playwright 的 Chrome/Chromium（`google-chrome-stable` 适用）
- 对于 `real` 模式：运行带有 `--remote-debugging-port=9222` 和专用 `user-data-dir` 的 Chrome 实例（参见 [使用 CDP 启动 Chrome](#使用-cdp-启动-chrome)）
## 安装
```bash
git clone https://github.com/q35888/agentic-browser-mcp.git
cd agentic-browser-mcp
npm install
```
## 配置您的 MCP 客户端
### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.agentic-browser]
type = "stdio"
command = "/usr/bin/node"
args = [ "/path/to/agentic-browser-mcp/index.mjs" ]
```
### 任意 MCP 客户端（stdio）
通过 stdio 启动 `node /path/to/agentic-browser-mcp/index.mjs` - 标准 MCP `initialize` → `tools/list` → `tools/call`。
### HTTP 模式（长期运行的单个实例）
```bash
node index.mjs --transport http --port 9223
# 向 http://127.0.0.1:9223/mcp 发送 MCP 请求
```
## 使用 CDP 启动 Chrome（适用于 `real` 模式）
Chrome 150+ 需要非默认用户数据目录进行远程调试。示例启动脚本：
```bash
#!/usr/bin/env bash
PROFILE="$HOME/.agentic-browser-chrome-profile"
mkdir -p "$PROFILE"
# 如果从非图形上下文启动，请填写图形会话环境变量
export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
export WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}"
exec google-chrome-stable \
--remote-debugging-port=9222 \
--user-data-dir="$PROFILE" \
--ozone-platform=wayland \
"$@"
```
> `--ozone-platform=wayland` 在 Chrome 从后台进程启动时非常重要：否则 Chrome 的平台启发式会选择 X11 并因 `Missing X server / Authorization required` 而失败。根据您的显示服务器调整（X11 用户：删除标志并确保设置了 `DISPLAY`/`XAUTHORITY`）。
如果您不手动启动 Chrome，服务器将尝试自动启动 `$HOME/.pi/agent/start-agent-chrome.sh`（在 `index.mjs` 中覆盖 `CHROME_STARTER` 以指向您自己的脚本）。
## 工具
| 工具 | 描述 |
|---|---|
| `browser_session` | 启动/切换会话（`real` / `isolated`，`headless`，`incognito`）。无参数 = 确保默认 `real`。 |
| `browser_navigate` | 打开一个 URL。 |
| `browser_snapshot` | 返回页面的 ARIA 树（YAML）。使用 `role`+`name` 进行 `click`/`type`。 |
| `browser_click` | 通过 `role`（+`name`）点击元素。 |
| `browser_type` | 通过 `role`（+`name`）填充输入框。 |
| `browser_eval` | 在页面中运行 JS 表达式（读取 DOM/存储/火请求）。 |
| `browser_storage` | 读取 `cookies` / `localStorage` / `sessionStorage`。 |
| `browser_console` | 读取缓冲的控制台日志（可选 `level` 过滤器）。 |
| `browser_wait_human` | 用于 CAPTCHA/手动步骤 - 返回提示；调用代理暂停并等待用户响应。 |
| `browser_screenshot` | 保存 PNG 图片到磁盘。 |
| `browser_close` | 关闭当前会话（`real` 仅断开 CDP，从不杀死 Chrome）。 |
## 备注
- **`browser_wait_human`**：此服务器无 GUI/TUI。它返回文本提示；客户端代理应显示它并等待用户响应。
- **会话共享**：连接到同一服务器的多个 MCP 客户端共享一个 Playwright 会话（因此共享一个 Chrome）。工具调用被序列化以防止竞争。
- **资源清理**：在 `stdin` EOF、传输关闭或 `SIGINT`/`SIGTERM` 时，服务器释放会话（带有 3 秒超时回退）- `isolated` 浏览器不会被孤立。
## 许可证
MIT
