Chrome Context MCP v2.0

Unified browser automation MCP server. Combines arbitrary JS execution in your real Chrome browser (with cookies and auth), accessibility tree snapshots with ref-based interaction, passive console/network capture, device emulation, and Lighthouse audits.

Architecture

Claude Code
    |  MCP (JSON-RPC 2.0 over HTTP)
    v
+-------------------------------------------+
|  mcp-server.js  (port 9223)              |
|  /mcp  — MCP protocol endpoint           |
|  /jobs — extension polls for pending jobs |
|  /results — extension posts results       |
|  /execute — legacy CLI endpoint           |
|  /health, /status — monitoring            |
|                                           |
|  + Lighthouse runner (headless Chrome)    |
+-------------------+-----------------------+
                    |
                    | HTTP polling (~6s)
                    v
+-------------------------------------------+
|  Chrome Extension (background.js)         |
|  Bundled from src/ modules via esbuild    |
|                                           |
|  Capabilities:                            |
|  - A11y tree snapshots via CDP            |
|  - Ref-based click/type/hover/drag        |
|  - Passive console + network capture      |
|  - Screenshots (viewport, full, element)  |
|  - Arbitrary JS execution                 |
|  - Tab management, navigation             |
|  - Device/viewport emulation              |
|  - PDF export, HTML extraction            |
+-------------------+-----------------------+
                    |
                    | chrome.debugger CDP 1.3
                    v
+-------------------------------------------+
|  Your Real Chrome Browser                 |
|  (cookies, auth, real sessions)           |
+-------------------------------------------+

Quick Start

1. Install dependencies

cd chrome-context
npm install

2. Build the extension

npm run build

3. Load the Chrome Extension

1. Open chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked → select chrome-context/extension/

4. Start the MCP server

npm start

5. Configure Claude Code

claude mcp add chrome-context http://localhost:9223/mcp

Available Tools (32)

Navigation & Tabs

Tool	Description
browser_tabs	List, create, close, or select tabs
browser_navigate	Navigate a tab to a URL
browser_navigate_back	Go back in history
browser_navigate_forward	Go forward in history
browser_reload	Reload the page

Accessibility Snapshots & Interaction

Tool	Description
browser_snapshot	Get accessibility tree with ref IDs
browser_click	Click element by ref
browser_type	Type text into element by ref
browser_fill_form	Fill multiple form fields
browser_select_option	Select dropdown option by ref
browser_hover	Hover over element by ref
browser_drag	Drag element to another by refs
browser_press_key	Press key or key combination
browser_scroll	Scroll page or element
browser_file_upload	Upload files to input by ref

Observation & Capture

Tool	Description
browser_take_screenshot	Screenshot (viewport, full-page, or element)
browser_console_messages	Get captured console messages
browser_network_requests	Get captured network requests
browser_get_network_request	Get response body of a request
browser_save_pdf	Save page as PDF
browser_get_html	Get page/element HTML
browser_handle_dialog	Accept/dismiss JS dialogs

JavaScript Execution

Tool	Description
browser_evaluate	Run JS via chrome.scripting (no debug banner)
browser_evaluate_debugger	Run JS via CDP (full power, shows banner)

Emulation & Device

Tool	Description
browser_resize	Set viewport size
browser_emulate_device	Emulate device (30+ presets)
browser_emulate_media	Dark/light mode, print media
browser_set_geolocation	Override geolocation
browser_wait_for	Wait for text/time/condition

Debugger Management

Tool	Description
browser_attach_debugger	Attach CDP debugger (enables passive capture)
browser_detach_debugger	Detach CDP debugger

Audits

Tool	Description
browser_lighthouse_audit	Run Lighthouse audit (separate headless Chrome)

Development

# Build extension from source modules
npm run build

# Watch mode (auto-rebuild on changes)
npm run build:watch

# Build and start server
npm run dev

# Start server only (extension must already be built)
npm start

After editing extension source files in extension/src/, rebuild and reload the extension at chrome://extensions/.

File Structure

chrome-context/
├── package.json
├── mcp-server.js           # MCP + Bridge server (port 9223)
├── context-executor.js     # CLI tool (backward compat)
├── build.js                # esbuild bundler
├── lib/
│   ├── tools.js            # Tool definitions + handlers
│   ├── devices.js          # Device preset registry
│   └── lighthouse.js       # Lighthouse audit runner
└── extension/
    ├── manifest.json
    ├── background.js       # Bundled service worker (built from src/)
    ├── popup.html
    ├── popup.js
    └── src/
        ├── main.js             # Entry: polling, dispatch, event listeners
        ├── bridge-polling.js   # HTTP polling communication
        ├── debugger-manager.js # CDP attach/detach lifecycle
        ├── snapshot-engine.js  # Accessibility tree + refMap
        ├── input-dispatcher.js # Ref-based click/type/hover/drag
        ├── screenshot-engine.js # Screenshots, PDF, HTML, dialog
        ├── passive-capture.js  # Console + network buffering
        └── emulation-engine.js # Device, viewport, geolocation