chromewright

Chromewright is a local-first browser automation MCP server built on Chrome DevTools Protocol (CDP). It exposes a real Chrome or Chromium browser to MCP clients over stdio or loopback streamable HTTP, with high-level tools for navigation, page reading, tab management, screenshots, viewport emulation, and bounded interaction.

Use Chromewright when an agent needs browser state from a real browser without embedding a Node.js automation stack or writing raw CDP calls. Chromewright is not an end-to-end test runner; it is a browser control layer for AI agents and MCP clients.

When to use Chromewright

• Attach an MCP client to an existing Chrome or Chromium profile on a DevTools endpoint.
• Launch a dedicated local browser session for agent work.
• Read pages through snapshots, markdown extraction, targeted inspection, and link inventory.
• Drive bounded interactions such as click, input, select, hover, key press, scroll, and wait.
• Capture managed PNG screenshots without letting callers choose arbitrary output paths.
• Reuse revision-scoped cursor handles from snapshots instead of relying only on CSS selectors.

Browser modes

Chromewright has two browser modes:

Examples:

# Default: attach to http://127.0.0.1:9222 and serve MCP over stdio.
chromewright

# Serve streamable HTTP on the default loopback endpoint.
chromewright serve

# Serve streamable HTTP on a custom port and path.
chromewright serve --port 3333 --http-path /browser

# Attach to a different DevTools endpoint.
chromewright --ws-endpoint http://127.0.0.1:9333

# Launch a visible browser with a dedicated profile.
chromewright --user-data-dir /tmp/chromewright-profile

# Launch a headless browser and serve streamable HTTP.
chromewright --headless --user-data-dir /tmp/chromewright-profile serve

CLI reference

Source: src/bin/mcp_server.rs.

Tool workflow

A typical agent workflow is:

1. Call tab_list or new_tab to establish an active tab.
2. Call snapshot to read the current page and collect actionable nodes.
3. Prefer a fresh cursor from snapshot or inspect_node when targeting follow-up actions.
4. Use inspect_node, get_markdown, extract, or read_links for more focused reads.
5. Use click, input, select, hover, press_key, scroll, wait, or tab tools for bounded interaction.
6. Call snapshot again after navigation, DOM-changing actions, viewport changes, or ambiguous target recovery.

snapshot supports these modes:

DOM-targeted tools accept a public target object:

{
  "target": {
    "kind": "selector",
    "selector": "h1"
  }
}

or:

{
  "target": {
    "kind": "cursor",
    "cursor": "<cursor from snapshot or inspect_node>"
  }
}

Selector strings are still accepted for compatibility by tools that use the public target type, but the object form is the canonical contract.

Production MCP tool surface

Production MCP sessions register the default high-level tools plus the guarded operator tool evaluate.

evaluate executes JavaScript in the active page and requires confirm_unsafe = true on each call. It is available for diagnostics and escape-hatch inspection when bounded tools cannot answer a page-specific question.

Source: src/tools/core/mod.rs and src/browser/session.rs.

Screenshots and viewport emulation

Use screenshot when a caller needs a managed PNG artifact. The tool accepts:

• mode: viewport, full_page, element, or region
• scale: device or css
• optional tab_id
• optional target for element captures
• optional region for region captures

Successful calls return managed artifact metadata, including artifact_uri, artifact_path, mime_type, byte_count, image dimensions, CSS dimensions, device pixel ratio, pixel scale, revealed_from_offscreen, and optional clip data. Callers do not provide output paths.

Use set_viewport to emulate responsive breakpoints through CDP. Successful calls return viewport_metrics_after; later snapshot calls expose the live metrics under scope.viewport.

Safety boundaries

• Attach mode can see the tabs, cookies, and authenticated state in the browser profile you connect to.
• Use a dedicated browser profile for agent work when you do not want automation attached to a personal browser session.
• evaluate requires confirm_unsafe = true because it runs arbitrary JavaScript in the active page.
• navigate and new_tab reject unsafe schemes such as data: and file: unless that request passes allow_unsafe = true.
• go_back and go_forward apply the same unsafe-scheme gate and revert rejected history moves.
• close_tab requires confirm_destructive = true before closing an unmanaged active tab in a connected session.
• close requires confirm_destructive = true before expanding connected-session cleanup from managed tabs to all tabs.
• cursor and node_ref targets are revision-scoped. After navigation or DOM-changing actions, refresh with snapshot.

Operation metrics

Finished tool results include operation_metrics metadata when a tool records non-zero metrics. operation_metrics.output_bytes is optional; it appears only when a tool path measures the exact serialized output size.

Measured paths may include:

• browser evaluation count
• poll iterations
• DOM extraction count and extraction time
• last DOM node count
• snapshot render time
• handoff rebuild count and time
• exact serialized output size when measured

Run the focused operation metrics tests:

cargo test --locked --all-features operation_metrics

Local development

Build from source:

cargo build

Run the normal test suite:

cargo test

Run the browser smoke suite from the repository root:

scripts/browser-smoke.sh

The smoke script runs:

cargo test --test browser_smoke -- --nocapture

Browser smoke checks launch a local browser and are intended for maintainer workstations. CI covers formatting, clippy, MSRV, cargo check, tests, and packaging without requiring a live browser attach target.

Source anchors

• Package metadata and Rust version: Cargo.toml
• CLI flags and transports: src/bin/mcp_server.rs
• Tool registry: src/tools/core/mod.rs
• MCP handler: src/mcp/handler.rs
• Public target contract: src/contract/target.rs
• Screenshot contract: src/tools/screenshot.rs
• Browser smoke script: scripts/browser-smoke.sh

License

MIT

Installation

Chromewright requires Rust 1.88 or newer when you install or build it with Cargo.

Install from crates.io:

cargo install chromewright

Install with Homebrew:

brew install bnomei/chromewright/chromewright

Install from source:

git clone https://github.com/bnomei/chromewright.git
cd chromewright
cargo install --path .

You can also download prebuilt archives from GitHub Releases and place the chromewright binary on your PATH.

Verify the binary is available:

chromewright --version

Expected output:

chromewright <version>

Quickstart

This path starts a visible Chrome profile with DevTools enabled, then serves Chromewright over loopback HTTP at http://127.0.0.1:3000/mcp.

Prerequisites

• chromewright on your PATH
• Chrome, Chromium, or another CDP-compatible browser
• An MCP client that supports streamable HTTP or stdio servers

1. Start a dedicated browser profile

On macOS, run:

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chromewright-agent-profile"

Use a dedicated profile when you do not want agent automation attached to your personal browser session. The default Chromewright attach mode expects DevTools at http://127.0.0.1:9222.

2. Start Chromewright

Run the streamable HTTP server:

chromewright serve

Expected log line:

Ready to accept MCP connections at http://127.0.0.1:3000/mcp

3. Connect an MCP client

For JSON-configured clients that support streamable HTTP:

{
  "mcpServers": {
    "chromewright": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

For Codex over stdio, let the client start the server:

[mcp_servers.chromewright]
command = "/absolute/path/to/chromewright"
enabled = true

For Codex against the long-lived HTTP server from step 2:

[mcp_servers.chromewright]
url = "http://127.0.0.1:3000/mcp"
enabled = true

4. Verify with the client

Use your MCP client to call tab_list. A connected session should return at least one tab with a stable tab_id. If no active tab is useful, call new_tab before calling snapshot.