chrome-dom-mcp

Control a real Chrome browser from Claude (or any MCP client): navigate, snapshot the DOM with element refs, click, type, screenshot, and run JS.

Demo

After install, try a prompt like:

use the chrome mcp to create the google ads campaign for this project

Claude opens your Chrome, reads the page structure, and drives the UI while you watch.

Related MCP server: Chrome Extension MCP Bridge

Architecture

Claude / MCP client
        |  stdio (MCP)
        v
  chrome-dom-mcp   (Node.js)
        |  WebSocket ws://127.0.0.1:17373
        v
  Chrome extension (MV3)
        |
        v
  Your Chrome tabs (DOM + screenshots)

Quick start

A. Install the MCP server

Claude Code:

claude mcp add chrome-dom-mcp -- npx -y chrome-dom-mcp

Claude Desktop (merge into your config file):

{
  "mcpServers": {
    "chrome-dom-mcp": {
      "command": "npx",
      "args": ["-y", "chrome-dom-mcp"]
    }
  }
}

Example configs also live in configs/.

B. Install the Chrome extension

Option 1: download a release zip

1. Get extension-dist.zip from GitHub Releases

2. Unzip it

3. Open chrome://extensions

4. Enable Developer mode

5. Load unpacked and select the unzipped folder

6. Pin chrome-mcp. The badge shows ON when the MCP server is connected.

Option 2: load from the npm package

After the first npx run (or npm install -g chrome-dom-mcp), the unpacked extension is inside the package:

node -e "const p=require('path');console.log(p.join(p.dirname(require.resolve('chrome-dom-mcp/package.json')),'extension'))"

Load that folder the same way (Developer mode → Load unpacked).

Option 3: build from source

See Install from source. Load packages/mcp-server/extension/ after bun run build.

C. Verify

Ask Claude:

use browser_status then snapshot my current tab

You should see connected: true and a DOM snapshot with refs like e1, e2.

Install from source

git clone https://github.com/imfaisii/chrome-dom-mcp.git
cd chrome-dom-mcp
bun install
bun run build

Point your MCP config at the local binary:

{
  "mcpServers": {
    "chrome-dom-mcp": {
      "command": "node",
      "args": ["/ABS/PATH/chrome-dom-mcp/packages/mcp-server/dist/index.js"]
    }
  }
}

Load the extension from packages/mcp-server/extension/.

Development commands:

bun run typecheck
bun run smoke
bun run pack:dry

Tools

Agent loop that works well:

1. browser_navigate or browser_tabs

2. browser_snapshot

3. browser_click / browser_type using refs from the snapshot

4. Snapshot again (refs go stale after navigation)

Temporary files

Snapshots and screenshots are written under:

/tmp/chrome-mcp/snapshots/*.txt
/tmp/chrome-mcp/screenshots/*.png

• Auto-pruned after 30 minutes, and capped at 40 files per kind

• Tool results include the saved path

• persistOnly: true returns only the path (handy when the body is huge)

• browser_clear_tmp deletes one path or wipes the whole tree

• /tmp is also cleared on reboot on many systems

Configuration

The extension currently hardcodes port 17373. Change both sides if you need another port.

Security

• The bridge listens on 127.0.0.1 only

• The extension can read and modify pages you visit and capture screenshots

• browser_evaluate runs arbitrary JS in the page. Treat MCP access like full browser control

• Prefer a dedicated Chrome profile for automation when you can

• See SECURITY.md for private vulnerability reporting

Limitations

• Viewport screenshots only (not full-page scroll)

• chrome:// and Chrome Web Store pages are blocked by Chrome

• MV3 service workers can sleep; an alarm + reconnect loop keeps the bridge healthy

• Cross-origin iframes are not walked by the snapshot

• One extension connection at a time (newest wins)

Not the same as npm chrome-mcp

npm already has an unrelated package named chrome-mcp (macOS DevTools / CDP). This project is chrome-dom-mcp: a Chrome extension bridge for real DOM snapshots and interaction on macOS, Windows, and Linux.

Contributing

See CONTRIBUTING.md.

License

MIT © Faisal Ashfaq