browser-store

<p align="center"> <strong>浏览器多开管理 CLI</strong> —— 基于 Chrome/Edge 内核多开独立浏览器实例，每个实例独立 profile 与会话数据、独立 CDP 远程调试端口，可把每个实例的浏览器能力通过 <strong>MCP Server</strong> 暴露给 AI 客户端（如 Claude Desktop），并内置 umijs 管理台。 </p>

<p align="center"> <a href="https://www.npmjs.com/package/@bysking/browser-store"><img src="https://img.shields.io/npm/v/@bysking/browser-store" alt="npm version"></a> <a href="https://www.npmjs.com/package/@bysking/browser-store"><img src="https://img.shields.io/npm/dt/@bysking/browser-store" alt="npm downloads"></a> <a href="https://github.com/bysking/browser-store/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT%20%2B%20商业授权-yellow.svg" alt="License"></a> <a href="https://github.com/bysking/browser-store/actions/workflows/ci.yml"><img src="https://github.com/bysking/browser-store/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/bysking/browser-store"><img src="https://img.shields.io/github/stars/bysking/browser-store" alt="GitHub stars"></a> </p>

<p align="center"> <code>npx -y @bysking/browser-store</code> </p>

目录

• 核心能力
• 安装
• 快速开始
• 命令参考
• MCP 接入 Claude Desktop
• 数据存储
• 安全说明
• 架构
• 开发
• 贡献
• License

核心能力

能力	说明
多开实例	每个实例独立 --user-data-dir profile 目录，会话 / cookies / 登录态互不影响
独立 CDP 端口	每实例自动分配独立 --remote-debugging-port（默认 9222 起，冲突自动 +1 重分配）
MCP Server	每实例可暴露为 MCP server，AI 客户端直接操控该浏览器（导航/截图/点击/填表/执行 JS 等 16 个工具）
生命周期	新增 / 编辑 / 删除 / 启动 / 关闭 / 重置（清 profile 还原），状态机完整管理
管理台	umijs 前端嵌入 CLI，bs serve 单端口出全站
发布	esbuild 单文件 bundle，npx 即装即用，无需安装浏览器驱动

安装

npm i -g @bysking/browser-store   # 全局安装
# 或
npx -y @bysking/browser-store     # 免安装直接使用

要求：Node.js >= 20.10.0

从源码构建：

git clone https://github.com/bysking/browser-store.git
cd browser-store
pnpm install
pnpm build                       # 产出 dist/cli.cjs + dist/public
node dist/cli.cjs --version      # 验证

快速开始

# 1. 探测本机已安装浏览器
bs discover

# 2. 新增实例
bs add work --engine chrome
bs add edge1 --engine edge --headless --urls https://example.com,https://github.com

# 3. 启动 / 停止 / 重启 / 重置
bs start work
bs stop work
bs restart work
bs reset work --yes          # 清空 profile 还原（自定义目录需 --force）

# 4. 即开即用：实例不存在自动创建，命令退出后浏览器保持运行
bs open work https://example.com

# 5. 查看状态 / 日志
bs ls
bs info work
bs logs work --follow

# 6. 启动常驻服务（API + 管理台 + HTTP MCP）
bs serve
# 浏览器打开 http://localhost:3210 进入管理台

# 7. 让 AI 操控浏览器（MCP）
bs mcp-register work          # 拿到 Claude Desktop 配置片段

帮助

$ bs --help

用法: bs [options] [command]

浏览器多开管理 CLI — 独立 profile / 独立 CDP 端口 / 每实例 MCP Server

选项:
  -v, --version              输出版本号
  -h, --help                 display help for command

命令:
  serve [options]            启动常驻服务（HTTP API + umijs 管理台 + 实例生命周期 + HTTP MCP）
  open [options] <name> [url] 即开即用：打开（必要时创建）实例并导航到 URL，命令退出后浏览器保持运行
  add [options] <name>       新增浏览器实例
  ls|list [options]          列出所有实例及状态
  start <name>               启动实例
  stop <name>                停止实例
  restart <name>             重启实例
  reset [options] <name>     重置实例：停止 + 清空 profile 还原（默认需确认）
  prune [options] [name]     清理实例的可再生缓存/指标目录（需先停止，不影响会话数据）
  rename <name> <newName>    重命名实例
  rm|remove [options] <name> 删除实例（需先停止）。默认保留 profile，--purge 连带删除
  mcp <name>                 为实例启动 stdio MCP server（供 Claude Desktop 等 AI 客户端接入）
  mcp-register <name>        打印/写入该实例的 Claude Desktop mcpServers 配置片段
  discover                   探测本机已安装浏览器
  doctor                     诊断：node 版本、浏览器、端口、CDP 可达性
  logs [options] <name>      查看实例日志
  info <name>                查看实例完整配置 + 状态 + CDP/MCP 地址

命令参考

命令	说明
bs serve [--port] [--host] [--stop-all-on-exit]	常驻服务：HTTP API + 管理台 + 生命周期 + HTTP MCP
bs open <name> [url] [--engine]	即开即用：打开（必要时创建）实例并导航，命令退出浏览器保持运行
bs add <name> [--engine] [--profile-dir] [--debug-port] [--mcp-port] [--headless] [--urls] [--mcp-transport]	新增实例
bs ls / list [--json]	列出实例及状态
bs start / stop / restart <name>	启停 / 重启
bs reset <name> [--yes] [--no-start]	重置：停止 + 清空 profile 还原
bs rename <name> <newName>	重命名
bs rm <name> [--yes] [--purge]	删除实例（交互选择是否连带删 profile，--purge 连带删）
bs mcp <name>	为该实例启动 stdio MCP server
bs mcp-register <name>	打印 Claude Desktop mcpServers 配置片段
bs discover	探测本机浏览器
bs doctor	诊断：node / 浏览器 / 端口 / CDP 可达性
bs logs <name> [--follow] [--tail N]	查看 / 跟随日志
bs info <name>	完整配置 + 状态 + CDP/MCP 地址

MCP 接入 Claude Desktop

对任一实例执行 bs mcp-register <name>，把输出的片段加入 Claude Desktop 配置，即可让 AI 直接操控该实例（详见 docs/claude-desktop-setup.md）。

HTTP 模式：bs serve 后每个运行中的实例暴露 http://localhost:<port>/mcp/<instanceId>（Streamable HTTP），任何标准 MCP 客户端可连接。

数据存储

全部 JSON 存储于本地（可用 BS_HOME 覆盖根目录）：

~/.browser-store/
├── instances.json   # 实例配置（用户可编辑）
├── state.json       # 运行时状态（daemon 独占写）
├── daemon.json      # daemon 发现信息（CLI 路由用）
├── profiles/<id>/   # 受管 profile 目录
└── logs/<id>.log    # 实例日志

安全说明

• CDP 调试端点仅监听 127.0.0.1，启动参数含 --remote-allow-origins=*（Chrome 111+ CDP WebSocket 必需），仅限本地可信环境
• reset 默认只清受管目录的 profile；自定义目录需 --force 并确认，防误删用户数据
• bs serve 退出默认不杀已启动的浏览器（--stop-all-on-exit 才全停），实例可被下次启动的 daemon 收养

架构

browser-store/
├── bin/bs.ts           # CLI 入口（esbuild bundle）
├── src/
│   ├── cli.ts          # commander 命令定义
│   ├── commands.ts     # 命令实现
│   ├── serve.ts        # 常驻服务 + daemon.json + 孤儿收养
│   ├── config/         # instances.json / state.json / 路径
│   ├── engines/        # BrowserEngine 可插拔（chrome / edge）
│   ├── instance/       # 端口分配 / spawn / 状态机 / 进程管理
│   ├── cdp/session.ts  # chrome-remote-interface 封装
│   ├── mcp/            # MCP 工具 + stdio + Streamable HTTP
│   └── api/            # REST + SSE 事件流
├── web/                # umijs 管理台（构建产物嵌入 dist/public）
└── docs/

详细规划见 docs/architecture-plan.md，功能与使用技巧见 docs/help-center.md。

开发

pnpm install
pnpm exec tsx bin/bs.ts --help     # dev 运行
pnpm typecheck                     # 类型检查
pnpm lint                          # 代码规范检查
pnpm build                         # esbuild bundle + web 构建 + 静态拷贝
node dist/cli.cjs --version        # 产物运行
pnpm test                          # 单元测试

贡献

欢迎参与贡献！请阅读 CONTRIBUTING.md 了解开发环境、提交规范与 PR 流程。提交前请确保 pnpm typecheck、pnpm lint、pnpm test 全部通过。

License

本项目采用 MIT + 商业授权 双许可模式：

• 个人 / 开源 / 学术用途：遵循 MIT 许可，完全免费
• 商业用途：需取得作者书面授权，详见 LICENSE