chrome-agent-mcp

Full Chrome control for AI agents via the Model Context Protocol

npm License: MIT Node.js

Give Claude (or any MCP client) full control over your browser: navigate pages, click elements, fill forms, inspect DevTools — with parallel tab execution, session isolation per agent, and a real-time dashboard.

What it does

Each Claude session gets its own Chrome tab group — so multiple agents can run in parallel without stepping on each other. A companion Chrome extension shows a live dashboard: active tabs, event log, and screenshots in real time.

Claude session A  →  tab group "Pinguim"  (blue)
Claude session B  →  tab group "Fenix"   (red)
Claude session C  →  tab group "Girafa"  (yellow)

Every tool call is wrapped with resilient execution:

20 s primary timeout
2× parallel retries on timeout (10 s each)
Automatic fallback to a new Chrome group if all retries fail

Requirements

Node.js ≥ 18
Google Chrome with remote debugging enabled

Installation

1. Enable Chrome remote debugging

google-chrome --remote-debugging-port=9222

To make it permanent, add the flag to your Chrome launcher or .desktop file.

2. Install the MCP server

# Run directly (no install)
npx chrome-agent-mcp

# Or install globally
npm install -g chrome-agent-mcp

3. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "chrome-agent-mcp": {
      "command": "npx",
      "args": ["chrome-agent-mcp"],
      "env": { "CHROME_DEBUG_PORT": "9222" }
    }
  }
}

Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "chrome-agent-mcp": {
      "command": "node",
      "args": ["/path/to/chrome-agent-mcp/dist/index.js"],
      "env": { "CHROME_DEBUG_PORT": "9222" }
    }
  }
}

4. Install the companion extension (optional but recommended)

Open chrome://extensions/
Enable Developer mode
Click Load unpacked → select the extension/ folder

The extension adds a popup dashboard showing which tabs are active, what the agent is doing, and captured screenshots — all updating in real time.

Available Tools

Tool	Description
`browser_navigate`	Navigate to a URL
`browser_navigate_back`	Go back in browser history
`browser_navigate_forward`	Go forward in browser history
`browser_reload`	Reload the current tab

Interaction

Tool	Description
`browser_click`	Click an element by accessibility ref
`browser_type`	Type text into a focused element
`browser_hover`	Hover over an element
`browser_press_key`	Press a keyboard key or shortcut
`browser_scroll`	Scroll the page or an element
`browser_select_option`	Select a `<select>` dropdown option
`browser_fill_form`	Fill multiple form fields at once
`browser_wait_for`	Wait for an element or condition

Page Inspection

Tool	Description
`browser_snapshot`	Get the accessibility tree of the page
`browser_take_screenshot`	Capture a full-page screenshot
`browser_evaluate`	Execute JavaScript and return the result

Tab Management

Tool	Description
`browser_tabs`	Open, close, switch, list, and mark tabs done

DevTools

Tool	Description
`devtools_console`	Read and clear browser console logs
`devtools_network`	Inspect network requests and responses
`devtools_elements`	Inspect and query DOM elements
`devtools_storage`	Read cookies, localStorage, sessionStorage

Browser Management

Tool	Description
`chrome_windows`	List all open Chrome windows
`chrome_focus`	Focus a specific window
`chrome_extensions`	List installed Chrome extensions
`session_sync`	Sync session state with the extension dashboard

Architecture

src/
├── index.ts              MCP server + request dispatch
├── types.ts              Shared type definitions
├── core/                 Infrastructure layer
│   ├── connection.ts     Chrome CDP connection lifecycle
│   ├── bridge.ts         Extension event bridge
│   ├── favicon.ts        Tab favicon animation manager
│   ├── resilience.ts     Timeout / retry / fallback execution
│   └── groups/           Tab group isolation
│       ├── manager.ts    Orchestrator (public API)
│       ├── state.ts      File-based state persistence
│       └── chrome-api.ts Chrome Extension API bridge
├── tools/                MCP tool implementations
│   ├── tabs.ts
│   ├── navigation.ts
│   ├── browser.ts
│   ├── media.ts          screenshot · snapshot · evaluate
│   ├── session.ts
│   ├── interaction/      click · type · hover · scroll · form · wait
│   └── devtools/         console · network · elements · storage
└── utils/                Pure utility functions
    ├── accessibility.ts  AX tree formatter
    ├── description.ts    Tab action labels
    └── identity.ts       Animal names + Chrome group colors

Engineering rules: every file ≤ 300 lines · every directory ≤ 7 items · SOLID principles throughout.

Configuration

Variable	Default	Description
`CHROME_DEBUG_PORT`	`9222`	Chrome remote debugging port

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Coverage report (target: 80%)
npm run coverage

chrome-agent-mcp

chrome-agent-mcp

What it does

Requirements

Installation

1. Enable Chrome remote debugging

2. Install the MCP server

3. Configure your MCP client

4. Install the companion extension (optional but recommended)

Available Tools

Navigation

Interaction

Page Inspection

Tab Management

DevTools

Browser Management

Architecture

Configuration

Development

License

Latest Blog Posts

MCP directory API