chromewright 0.2.3

Browser automation MCP server and Rust library via Chrome DevTools Protocol (CDP)
Documentation

chromewright

A lightweight Rust library for browser automation via Chrome DevTools Protocol (CDP).

✨ Highlights

  • Zero Node.js dependency - Pure Rust implementation directly controlling browsers via CDP
  • Lightweight & Fast - No heavy runtime, minimal overhead
  • MCP Integration - Built-in Model Context Protocol server for AI-driven automation
  • Simple API - High-level document tools for navigation, interaction, and extraction

Installation

Binary From Crates.io

cargo install chromewright

Library Dependency

If you only want the embeddable Rust library surface and not the standalone server binary dependencies:

cargo add chromewright --no-default-features

Enable mcp-handler explicitly if you need the in-process MCP module without the standalone CLI:

chromewright = { version = "0.2.3", default-features = false, features = ["mcp-handler"] }

From Source

cargo install --path .

Quick Start

use chromewright::browser::BrowserSession;

// Launch browser and navigate
let session = BrowserSession::launch(Default::default())?;
session.navigate("https://example.com")?;

// Extract DOM with revision-scoped document metadata
let dom = session.extract_dom()?;
println!("Current revision: {}", dom.document.revision);

MCP Server

Run the built-in MCP server for AI-driven automation:

# Headless local browser over stdio
cargo run --bin chromewright

# Visible local browser over stdio
cargo run --bin chromewright -- --headed

# Connect to an existing Chrome DevTools WebSocket instead of launching Chrome
cargo run --bin chromewright -- \
  --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>

# Expose streamable HTTP transport on localhost:3000/mcp
cargo run --bin chromewright -- --transport http

Recommended macOS launch command for a visible dedicated Chrome session that this repo can reconnect to reliably:

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

Use this when you want a headed browser without attaching to your personal Chrome profile. After Chrome is running, point the MCP server at the DevTools browser WebSocket exposed on port 9222.

Supported browser-mode flags:

  • --headed
  • --executable-path <PATH>
  • --user-data-dir <DIR>
  • --debug-port <PORT>
  • --ws-endpoint <URL> for remote browser connections

Supported transports:

  • stdio (default)
  • http via streamable HTTP on --port and --http-path

Features

  • Default high-level agent tools for snapshot, navigate, click, input, wait, tabs, and extraction
  • DOM extraction with revision-scoped node references and iframe metadata
  • Metadata-first post-action envelopes for high-level tools, with the full snapshot surface kept on the snapshot tool
  • CSS selector, numeric index, or node_ref targeting for document interactions
  • Explicit operator opt-ins for raw JavaScript evaluation and filesystem-bound screenshots
  • Thread-safe browser session management

Tool Surfaces

The default ToolRegistry and MCP server expose the high-level document interaction contract. Raw JavaScript evaluation and path-based screenshot capture are intentionally outside that default surface. High-level action tools now return updated document metadata by default; call snapshot when you need the full YAML snapshot plus actionable-node list. See docs/tool-description-index.md for the concise tool-description index and wording rules.

For direct Rust integrations, opt into those operator tools explicitly:

use chromewright::tools::ToolRegistry;

let mut registry = ToolRegistry::with_defaults();
registry.register_operator_tools();

Once operator tools are registered, evaluate and screenshot still require confirm_unsafe = true per call. High-level navigate and new_tab also reject unsafe schemes such as data: and file: unless the caller passes allow_unsafe = true.

Requirements

  • Rust 1.85+
  • Chrome or Chromium installed

Release Plan

The repository is set up to support both crates.io distribution and GitHub release archives for the chromewright binary. The fastest way to reserve the crate name is to publish the package to crates.io first, then attach prebuilt archives from tagged GitHub releases.

Acknowledgments

This project was inspired by and references agent-infra/mcp-server-browser.

License

MIT