@cjwddz/browser-server

面向 AI Agent 的自托管常驻浏览器服务。

解决的问题

AI Agent 在无 GUI 的远程服务器上操作浏览器时面临的核心难题：

• 浏览器生命周期绑定 Agent 对话，对话结束状态全丢
• 跨天登录态无法保持，每次都要重新登录
• 验证码、密码等场景 AI 无法处理，卡住无解
• 多 Agent 共用浏览器互相干扰

核心特性

• 常驻浏览器 — 浏览器 7×24 运行，不因 Agent 会话结束而关闭
• 状态完整保持 — Cookie、localStorage、页面 JS 上下文持续存活，跨天登录态不丢
• Web 端实时操控 — 用户随时从浏览器打开管理页面，直接查看和操作浏览器（验证码、密码等）
• Agent 隔离 — 每个会话独立 BrowserContext，Cookie/存储完全隔离
• MCP 集成 — 15 个浏览器操控工具，支持 Streamable HTTP 协议
• 进程守护 — Chromium 崩溃自动重启

系统依赖

# Ubuntu/Debian
sudo apt-get install -y xvfb x11vnc chromium-browser

安装

npm install -g @cjwddz/browser-server

使用

启动服务

browser-server start -u admin -p mypassword

完整参数

browser-server start \
  -u admin \           # Web 管理登录用户名（必填）
  -p mypassword \      # Web 管理登录密码（必填）
  -w 33000 \           # Web 管理端口（默认 33000）
  -m 33001 \           # MCP 服务端口（默认 33001）
  -d ~/.browser-server \ # 服务根目录（默认 ~/.browser-server）
  --host 0.0.0.0       # 监听地址（默认 0.0.0.0）

其他命令

browser-server stop       # 停止服务
browser-server restart -u admin -p mypassword  # 重启
browser-server status     # 查看状态

使用流程

1. 启动服务
2. 浏览器打开 http://localhost:33000，输入账号密码
3. 点「新建会话」，输入名称
4. 点「MCP 配置」，复制 JSON 配置
5. 粘贴到 Cursor / Claude Desktop 的 MCP 配置中
6. Agent 开始操作浏览器
7. 需要人工介入时（验证码等），在管理页面点「查看浏览器」直接操作

架构

browser-server
├── Web 管理 (:33000)          ← 用户浏览器访问
│   ├── 会话列表（创建/删除）
│   ├── 查看浏览器（noVNC 实时画面 + 操作）
│   └── MCP 配置（一键复制）
│
├── MCP 服务 (:33001)          ← Agent 连接
│   └── 15 个浏览器操控工具
│
└── 每个会话 = 独立进程组
    ├── Xvfb (虚拟显示器)
    ├── Chromium (--user-data-dir 持久化)
    └── x11vnc (VNC 服务)

MCP 工具列表

| 工具 | 说明 | |------|------| | navigate_page | 导航到指定 URL | | click | 点击页面元素 | | fill | 填写输入框 | | hover | 悬停在元素上 | | press_key | 按下键盘按键 | | take_screenshot | 截取页面截图 | | take_snapshot | 获取页面 DOM 快照 | | evaluate_script | 执行 JavaScript | | list_pages | 列出所有标签页 | | new_page | 打开新标签页 | | close_page | 关闭当前标签页 | | select_page | 切换标签页 | | wait_for | 等待元素出现或指定时间 | | emulate | 模拟移动设备 | | resize_page | 调整视口大小 |

数据目录结构

~/.browser-server/
├── server.pid          # 守护进程 PID
├── server.json         # 运行配置
├── sessions.json       # 会话列表
├── server.log          # 服务日志
├── <session-id>/       # 会话目录
│   ├── chrome-data/    # Chromium 用户数据（cookie/storage 等）
│   └── chrome.log      # Chromium 日志
└── ...

Docker 部署

适用于 macOS / Windows / 任何不想手动安装系统依赖的场景：

# 构建镜像
cd packages/browser-server
npm run build
docker build -t browser-server .

# 运行
docker run -d \
  -p 33000:33000 \
  -p 33001:33001 \
  -v ~/.browser-server:/data \
  browser-server start -u admin -p mypassword -d /data --host 0.0.0.0

镜像内已包含 Chromium、Xvfb、x11vnc 和中文字体，无需额外配置。

License

MIT