Chrome Control MCP

Visible, precise Chrome control for AI assistants. Local by design.

Quick start · Tool catalog · Architecture · Security · Verification

Active automation stays visible: pink frame, AI CONTROL badge, and pulsing agent cursor show when an assistant controls Chrome. Model-facing screenshots hide this overlay by default; documentation captures can opt in.

Why this project

All 43 MCP tools use strict JSON Schemas. Long-lived MCP process preserves session and element-ref state while Chrome remains an ordinary user-controlled browser.

Related MCP server: Chrome MCP Server

See it work

Both images are direct browser_screenshot results from live extension, not mockups.

Testing shout-out: Inflectra's UI Test Automation Playground and open-source repository provide focused, practical browser interaction scenarios. They have been invaluable for testing this project's full MCP-to-Chrome path.

Quick start

1. Install build requirements

• Windows 10/11 x64, Linux x64, or macOS

• Google Chrome 116+

• CMake 3.25+

• Qt 6.5+ with Core and Test components

• C++20 compiler: Visual Studio 2022, GCC, or Clang

• Node.js 20.19+

2. Build and test

npm ci
npm run build

Default output:

PowerShell users may run ./scripts/build.ps1 -Configuration Release instead. Both paths build with warnings-as-errors and run all native plus extension unit suites.

3. Prepare Chrome

npm run extension -- install

Open chrome://extensions, enable Developer mode, choose Load unpacked, then select folder printed by command. Chrome requires this one manual step for an unpacked extension.

No signing key, packaged extension, store account, administrator access, or enterprise policy is needed. Public key in manifest.json only pins unpacked extension ID; it cannot sign software.

4. Connect an assistant

Use absolute executable path.

# Windows
codex mcp add chrome-control -- "C:\absolute\path\chrome_control_mcp.exe"

# Linux / macOS
codex mcp add chrome-control -- /absolute/path/chrome_control_mcp

Claude Code uses same executable:

claude mcp add --scope local chrome-control -- /absolute/path/chrome_control_mcp

Transport is newline-delimited JSON-RPC over stdio. Server opens no TCP listener.

Architecture

flowchart LR
    A[AI assistant] -->|MCP over stdio| B[chrome_control_mcp]
    B -->|Windows named pipe<br/>Linux/macOS Unix socket| C[Native-host relay]
    C -->|Chrome native messaging| D[Unpacked MV3 extension]
    D -->|Chrome DevTools Protocol| E[Active Chrome tab]

One executable serves MCP server and native-host relay roles. Browser control belongs in MCP because it needs callable tools, image results, hardened IPC, and persistent session state. A skill may add workflows, but does not replace server.

Security model

Full control is powerful. Chrome Control MCP pins extension origin, limits and validates IPC, authenticates same-user/same-executable relay, rejects stale element refs and screenshot coordinates, bounds major payloads, and exposes strict schemas.

Windows uses current-user ACL-protected named pipe. Linux and macOS use mode-0600 Unix socket inside private runtime directory plus operating-system peer credentials.

For inspection-only use:

CHROME_CONTROL_MCP_SECURITY_PROFILE=read_only
CHROME_CONTROL_MCP_REDACT_SENSITIVE_OUTPUT=true

Read-only profile exposes 10 tools and independently rejects hidden mutating calls.

Verification

Local Windows and Linux gates currently cover:

• 9/9 native and extension suites with MSVC, GCC, and Clang

• Warnings-as-errors plus clang-tidy and exhaustive cppcheck

• Separate ASan+UBSan and TSan runs

• Full-history Gitleaks scan and npm dependency audit

• 43/43 live MCP tools through real Chrome on Windows

• Public UI Playground navigation, snapshot, typing, click, and PNG capture

• Reversible native-host install/status/uninstall lifecycle

GitHub Actions builds and tests Windows, Linux, and macOS on every direct push.

npm run smoke
npm run smoke:read-only
node tests/e2e/full_browser_e2e.mjs

PowerShell live public-site check:

./scripts/live_browser_verify.ps1 -Site http://uitestingplayground.com/

See exact evidence and claim boundaries.

Project identity

Unregister current-user native host with npm run extension -- uninstall, then remove unpacked extension manually from chrome://extensions when retiring it.

License

Released under MIT License. Copyright © 2026 Randy Northrup.