@apireno/domshell

MCP server that turns your browser into a filesystem. AI agents use ls, cd, grep, find, click, and type to browse the web — the same way you'd navigate a Linux filesystem.

DOMShell maps Chrome's Accessibility Tree to a virtual filesystem. Every DOM element becomes a file or directory. Agents work with familiar commands instead of raw selectors and coordinates.

Install

npm install -g @apireno/domshell

Or run directly:

npx @apireno/domshell

You also need the DOMShell Chrome Extension — the MCP server talks to the browser through it.

Quick Start

npx @apireno/domshell init

The setup wizard detects installed MCP clients (Claude Desktop, Cursor, Windsurf), generates a secure token, and writes the config. Use --yes for non-interactive mode.

Then:

1. Install the DOMShell Chrome Extension
2. Open Chrome's side panel and start a DOMShell session
3. Restart your MCP client — DOMShell tools will appear
4. In the DOMShell terminal, run connect <token> (printed by the wizard)

Claude Desktop Config

Add this to your Claude Desktop MCP settings (claude_desktop_config.json):

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

For the stdio proxy (required if your client needs command/args format):

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

Benchmarks

We tested DOMShell against Computer-in-the-Cloud (CiC) — both using Claude as the underlying model — across 4 web tasks over 8 trials.

DOMShell uses 2× fewer API calls to complete the same tasks. The filesystem metaphor gives the model a mental map of the page, so it spends less time exploring and more time extracting.

Full experiment data: experiments/claude_domshell_vs_cic

MCP Interface

Default (recommended): the single domshell_execute tool. Pass any DOMShell command as a string — "ls", "cd tabs/123", "open https://example.com" — or pass several newline-separated for a whole workflow in one call. One tool, one approval, the full command vocabulary in the tool description.

Multi-line semantics: when command contains newlines, each line runs in order in the same MCP session and lane, so cwd, env, and history persist between lines. An error on one line does not halt the rest — its message is included in the combined output and subsequent lines still run. This is the right shape for cleanup-line idioms like "cd path\ngrep pattern\ncd back": the trailing restore runs even if the middle step errors. Implementation: mcp-server/index.ts:1115-1136.

Lanes & multi-agent. Every reply ends with [lane: <id>]. Multiple MCP clients can connect simultaneously, each in its own isolated Chrome tab group. To carve sub-lanes within a single client (e.g. two Claude Desktop chats), pass group_id: "new" on the first call and carry the returned id thereafter. See CHANGELOG.md.

Granular mode — --granular

Start the server with --granular and the 38 per-command tools are exposed alongside domshell_execute. Use it when you want per-operation approval in the client UI.

Read tier (always available): ls, cd, pwd, cat, find, grep, tree, text, read, tabs, here, refresh, diff, eval, functions, watch, for, script, each, extract_links, extract_table

Write tier (--allow-write): click, focus, type, scroll, navigate, open, submit, back, forward, close, select, js, screenshot, wait, call

Sensitive tier (--allow-sensitive): whoami

CLI Flags

Security

Every command goes through a 4-tier security model:

• Read — always allowed (ls, find, grep, text)
• Navigate — requires --allow-write (navigate, open, back, forward)
• Write — requires --allow-write (click, type, js, select)
• Sensitive — requires --allow-sensitive (whoami, cookie access)

All commands are logged to an audit file. Domain allowlists restrict which sites the agent can access. Auth tokens protect the HTTP endpoint.

Architecture

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

Links

• Chrome Web Store: pireno.com/domshell
• GitHub: github.com/apireno/DOMShell
• Blog: Why I Built a Filesystem for the Browser
• Project home: pireno.com/domshell

Built by Pireno.

License

MIT