DOMShell

@apireno/domshell

可将浏览器变成文件系统的 MCP 服务。AI Agent 使用 ls、cd、grep、find、click 和 type 浏览网页，就像浏览 Linux 文件系统一样。

DOMShell 会将 Chrome 的无障碍树映射为虚拟文件系统。每个 DOM 元素都会变成一个文件或目录。Agent 使用熟悉的命令，而不是原始选择器和坐标。

安装

DOMShell 支持 三种安装方式，请选择适合你配置的一种。方式 1 是文档中默认的安装方式，适合 99% 的用户；方式 2 和 3 则适用于希望统一管理多个 MCP 服务生命周期的情况。

方式 1 — 原生 CLI（默认，最简单）

npm install -g @apireno/domshell

也可以直接运行，无需安装：

npx @apireno/domshell

支持 macOS、Linux 和 Windows，要求 Node 18 或更高版本。无需其他配置。

方式 2 — Docker 容器化（可选）

在容器中运行 DOMShell——适合不想全局安装 Node，或希望隔离进程的情况。需要 Docker Desktop。令牌会保存到被 git 忽略的 .env 文件中，因此容器重启或主机重启后仍会保留：

git clone https://github.com/apireno/DOMShell && cd DOMShell/mcp-server
cp .env.example .env
# Edit .env and set DOMSHELL_TOKEN to: $(openssl rand -hex 24)
docker compose build      # produces domshell-mcp-server:latest
docker compose up -d
docker compose logs -f

容器会将端口 3001（MCP HTTP）和 9876（连接 Chrome 扩展的 WebSocket 桥接端口）映射到本机回环接口，因此 Chrome 扩展可以像连接原生安装一样连接到它。restart: unless-stopped 会在 Docker Desktop 启动时自动重新启动容器（在 Docker Settings 中开启“登录时启动 Docker Desktop”，即可让方式 2 在重启后自动恢复运行）。

方式 3 — 由 ToolHive 管理（可选）

使用 ToolHive（thv）管理此容器的生命周期，并与运行中的其他 MCP 服务一并管理。与方式 2 使用同一个 .env 文件，只是由 thv 加载：

brew tap stacklok/tap && brew install thv      # one-time
cd DOMShell/mcp-server
cp .env.example .env       # edit DOMSHELL_TOKEN if you haven't already
docker compose build       # produces domshell-mcp-server:latest

thv run \
  --name domshell-mcp-server \
  --transport streamable-http \
  --target-port 3001 \
  -p 9876:9876 \
  --env-file .env \
  domshell-mcp-server:latest

thv list                          # workload status (URL on the proxy port)
thv logs domshell-mcp-server      # tail logs

由于 --target-port 3001 会自动将该端口发布到主机回环接口，因此可通过 http://127.0.0.1:3001/mcp 访问容器——现有的 MCP 客户端配置（Claude Desktop、Cursor 等）无需修改即可继续使用。

方式 3 需要一次性设置 launchd Agent，以便在重启后自动启动（方式 2 仅通过 Docker Desktop 即可在重启后恢复运行）。完整的重启对照表、launchd plist 模板、自动启动脚本和模拟重启验证，请参阅：docs/deploy/container-and-toolhive.md。

Chrome 扩展（以上三种方式均为必需）

你还需要安装 DOMShell Chrome Extension——MCP 服务通过它与浏览器通信。

快速入门

npx @apireno/domshell init

设置向导会检测已安装的 MCP 客户端（Claude Desktop、Cursor、Windsurf），生成安全令牌并写入配置。使用 --yes 可进入非交互模式。

然后：

1. 安装 DOMShell Chrome Extension
2. 打开 Chrome 侧边栏并启动 DOMShell 会话
3. 重启 MCP 客户端——此时会显示 DOMShell 工具
4. 在 DOMShell 终端中运行 connect <token>（令牌由向导输出）

Claude Desktop 配置

将以下内容添加到 Claude Desktop 的 MCP 设置中（claude_desktop_config.json）：

{
  "mcpServers": {
    "domshell": {
      "command": "npx",
      "args": ["-y", "@apireno/domshell", "--allow-write"]
    }
  }
}

对于 stdio 代理（客户端需要使用 command/args 格式时必需）：

{
  "mcpServers": {
    "domshell": {
      "command": "npx",
      "args": ["-y", "-p", "@apireno/domshell", "domshell-proxy", "--port", "3001", "--token", "YOUR_TOKEN"]
    }
  }
}

基准测试

我们在 8 次试验中，针对 4 项网页任务测试了 DOMShell 与 Computer-in-the-Cloud（CiC）的表现，两者都使用 Claude 作为底层模型。

指标	DOMShell	CiC
每项任务的平均 API 调用次数	4.3	8.6
最难任务（T4）	6.0 次调用	13.0 次调用
冷启动与 CiC 热缓存对比	4.5 次调用	5.5 次调用

DOMShell 完成相同任务所需的 API 调用次数减少一半。文件系统的隐喻为模型提供了页面的概念地图，因此它可以减少探索所花的时间，将更多时间用于提取信息。

完整实验数据：experiments/claude_domshell_vs_cic

MCP 接口

默认（推荐）：单个 domshell_execute 工具。 将任意 DOMShell 命令作为字符串传入——"ls"、"cd tabs/123"、"open https://example.com"——也可以用换行符分隔多条命令，在一次调用中完成整个工作流。一个工具、一次审批，工具描述中包含完整的命令词汇表。

多行语义： 当 command 包含换行符时，每一行都会按顺序在同一个 MCP 会话和通道中运行，因此 cwd、环境变量和历史记录会在各行之间保留。某一行出错不会中止其余命令——错误消息会包含在合并后的输出中，后续行仍会运行。这适用于 "cd path\ngrep pattern\ncd back" 这类清理行惯用写法：即使中间步骤出错，最后的恢复命令也会运行。实现：mcp-server/index.ts:1115-1136。

通道与多 Agent。 每条回复都以 [lane: <id>] 结尾。多个 MCP 客户端可以同时连接，每个客户端都有独立隔离的 Chrome 标签页组。要在单个客户端中划分子通道（例如两个 Claude Desktop 聊天），请在首次调用时传入 group_id: "new"，之后继续使用返回的 ID。参见 CHANGELOG.md。

细粒度模式 — --granular

使用 --granular 启动服务后，除 domshell_execute 外还会公开 38 个按命令划分的工具。如果你希望在客户端界面中逐项审批，请使用此模式。

读取级别（始终可用）： ls、cd、pwd、cat、find、grep、tree、text、read、tabs、here、refresh、diff、eval、functions、watch、for、script、each、extract_links、extract_table

写入级别（--allow-write）： click、focus、type、scroll、navigate、open、submit、back、forward、close、select、js、screenshot、wait、call

敏感级别（--allow-sensitive）： whoami

CLI 标志

标志	描述
--allow-write	启用写入级别工具（click、type、navigate 等）
--allow-sensitive	启用敏感级别工具（whoami）
--allow-all	启用所有级别
--granular	除 domshell_execute 外还公开 38 个按命令划分的工具
--port N	WebSocket 端口（默认：9876）
--mcp-port N	HTTP MCP 端口（默认：3001）
--domains a.com,b.com	限制为指定域名
--token TOKEN	设置身份验证令牌（若省略则自动生成）
--log-file PATH	审计日志位置（默认：audit.log）
--confirm	选择启用：每次写入前，在服务终端中逐项显示 y/n 确认提示。默认关闭。
--no-confirm	空操作（为保持向后兼容而保留——默认关闭逐项确认提示）。

安全性

每条命令都会经过 4 级安全模型：

• 读取 — 始终允许（ls、find、grep、text）
• 导航 — 需要 --allow-write（navigate、open、back、forward）
• 写入 — 需要 --allow-write（click、type、js、select）
• 敏感 — 需要 --allow-sensitive（whoami、Cookie 访问）

所有命令都会记录到审计文件中。域名允许列表会限制 Agent 可访问的网站。身份验证令牌用于保护 HTTP 端点。

架构

MCP Client (Claude, Cursor, etc.)
    ↓ HTTP :3001/mcp
DOMShell MCP Server (Express + WebSocket)
    ↓ WebSocket :9876
DOMShell Chrome Extension (CDP 1.3)
    ↓ Chrome Debugger Protocol
Browser DOM + Accessibility Tree

链接

• Chrome 网上应用店：pireno.com/domshell
• GitHub：github.com/apireno/DOMShell
• 博客：我为何为浏览器构建文件系统
• 项目主页：pireno.com/domshell

由 Pireno 构建。

许可证

MIT