Chromate MCP

Chromate MCP is a Model Context Protocol server for Chrome tab automation over the Chrome DevTools Protocol (CDP). It is designed for AI agents that work from screenshots: select a tab, inspect a coordinate grid, click CSS viewport coordinates, then receive an after screenshot.

Capabilities

• Connect to Chrome remote debugging from a fixed endpoint, Chrome 144+ auto-connect metadata, or local CDP port discovery.
• List and select Chrome tabs by CDP target id.
• Capture viewport screenshots with an optional grid and crosshair overlay.
• Click, scroll, type text, press keys, wait, and read page/viewport info.
• Keep all coordinates in CSS viewport pixels, matching CDP mouse events.

Chromate controls the web page content area. It does not operate the Chrome address bar, native tab strip, extension popups, file pickers, or OS windows.

Install

npm install
npm run build

Start Chrome

Chromate does not launch Chrome automatically. It can connect to an already-running Chrome in two ways.

For Chrome 144+, open chrome://inspect/#remote-debugging in Chrome and enable remote debugging. Chromate reads Chrome's DevToolsActivePort metadata by default and connects to the running browser after Chrome shows and you approve the permission dialog.

For older Chrome versions or sandbox/VM setups, start Chrome with a remote debugging port:

google-chrome-stable \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chromate-profile

Chromate auto-discovers local Chrome on ports 9222, 9223, 9224, and 9333 when CHROMATE_CDP_ENDPOINT is not set. Any Chromium-based browser that exposes CDP can work if it supports /json/version and a browser-level WebSocket endpoint.

MCP Configuration

Example client configuration:

{
  "mcpServers": {
    "chromate": {
      "command": "node",
      "args": ["/data0/chromate/dist/index.js"],
      "env": {}
    }
  }
}

Set CHROMATE_CDP_ENDPOINT only when you want to force a specific CDP HTTP or WebSocket endpoint.

During development, use:

npm run dev

Environment

• CHROMATE_CDP_ENDPOINT: CDP HTTP or WebSocket endpoint. If omitted, Chromate auto-discovers local CDP.
• CHROMATE_AUTO_CONNECT: read Chrome 144+ DevToolsActivePort metadata before scanning ports. Default: true
• CHROMATE_AUTO_CONNECT_CHANNEL: Chrome channel for default profile lookup: stable, beta, dev, or canary. Default: stable
• CHROMATE_AUTO_CONNECT_USER_DATA_DIR: explicit Chrome user data directory containing DevToolsActivePort
• CHROMATE_CDP_DISCOVERY_PORTS: comma-separated local ports to scan. Default: 9222,9223,9224,9333
• CHROMATE_DISCOVERY_TIMEOUT_MS: per-port discovery timeout. Default: 350
• CHROMATE_CONNECT_TIMEOUT_MS: connection timeout. Default: 10000
• CHROMATE_ACTION_TIMEOUT_MS: command timeout. Default: 30000
• CHROMATE_SETTLE_DELAY_MS: wait after auto actions. Default: 500
• CHROMATE_GRID_STEP: screenshot grid spacing. Default: 100
• CHROMATE_LOG_LEVEL: silent, error, info, or debug. Default: info

Workflow

1. Call list_tabs.
2. Call select_tab with the desired tabId.
3. Call screenshot and inspect the grid.
4. Call click with CSS viewport coordinates.
5. Use the returned after screenshot to continue.

See docs/tool-contract.md for the full tool contract.