<div align="center">

chrome-agent-mcp

Full Chrome control for AI agents via the Model Context Protocol

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.

</div>

---

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)

1. Open chrome://extensions/
2. Enable Developer mode
3. 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

Navigation

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

---

License

MIT © Otavio Senne