OpenChrome Browser Automation MCP Server

OpenChrome provides a comprehensive suite of 121 tools designed for browser automation, web crawling, and agentic workflows. These tools are categorized into several functional domains:

• Core: Fundamental browser interaction, DOM manipulation, network interception, and session management.
• Crawl: Tools for recursive website crawling, sitemap processing, and parallel batch execution.
• Profile: Management of Chrome profiles.
• Recording: Session recording and export capabilities.
• Storage: Management of cookies and web storage (localStorage/sessionStorage).
• TOTP: Generation of 2FA codes.
• Workflow: Orchestration of multiple workers for parallel browser operations.

The admin keys command group allows for the lifecycle management of tenant API keys.

Output Contract:

• stdout: Contains only the plaintext key (during create or rotate) or a JSON array (during list --json). This allows for clean piping into tools like jq.
• stderr: Contains all diagnostic information, tables, warnings, and error messages.

openchrome admin keys create --tenant acme --scope read --scope write

If an operation needs to be interrupted, send the standard MCP notifications/cancelled notification using the original requestId.

Cancellation Behavior:

• Pre-dispatch: If interrupted before the command is sent, the execution state is reported as not_started.
• Post-dispatch: If interrupted after the command is sent to Chrome, the execution state is reported as unknown and retryAllowed is set to false.
• Limitations: Cancellation stops further admission of commands but cannot roll back actions that have already been sent (like a click, a request, or a script execution). Always inspect the page state or server-side receipts to determine if a retry is safe.

Playbooks execute sequentially. If a step fails:

1. The step is marked failed in the report.
2. All subsequent steps are marked skipped (their MCP tools are not called).
3. The runner disconnects and exits with code 1.

Exit Codes:

• 0: All steps and all asserts passed.
• 1: At least one step or assert failed.
• 2: Usage, parse, or unknown variable error.
• 3: I/O, spawn, or transport failure (MCP server unreachable).

OpenChrome supports three transport modes to determine how clients interact with the server:

• stdio (Default): Best for single MCP clients (like Claude Desktop or Cursor) that launch the process and control its lifetime. The process exits when the client exits.
• http: Best for long-running daemons shared by multiple clients, CI jobs, or callers on different hosts. It allows concurrent connections and uses an idle-timeout to manage its own lifecycle.
• both: Best when an MCP client launches the process but a sidecar (like a dashboard or monitoring script) also needs to poll /health or /metrics. stdio carries MCP traffic, while HTTP carries the health/metrics side-channel.

Rule of thumb: Use --transport http if you are running OpenChrome in a Procfile, systemd unit, Docker CMD, or a CI step that outlives a single test run.

Outcome Contracts provide a machine-checkable way to prove that a skill or action (e.g., clicking a button) succeeded. They use a Domain Specific Language (DSL) to define postconditions that the OpenChrome runtime evaluates against a live Chromium page.

Contracts can be composed using logical operators:

• and: All children must pass. Short-circuits if a child fails.
• or: At least one child must pass. Short-circuits if a child succeeds.
• not: The single child must fail to satisfy the assertion.

If an assertion fails, the runtime escalates based on the contract's on_fail policy and emits an evidence bundle.

{
  "kind": "and",
  "children": [
    { "kind": "url", "pattern": "/orders/[A-Z0-9]{8}/confirmation" },
    { "kind": "dom_text", "selector": "h1", "contains": "Thank you" },
    { "kind": "no_dialog" }
  ]
}

A profile fingerprint is a deterministic, secret-free hash computed from a captured EnvelopeCapture. It allows two parties to verify if they are looking at the same authenticated session without exchanging sensitive data like actual cookie values or storage contents.

Key characteristics:

• Deterministic: The same input always produces the same hash.
• Value-Agnostic: It hashes the shape of the data (e.g., field names, value lengths) rather than the values themselves. Changing a cookie's value without changing its length will not change the fingerprint.
• Length-Sensitive: Changing the length of a value will change the fingerprint.
• Non-Cryptographic: It is intended for session comparison and diagnostic purposes, not for authentication or tamper detection.

The core category contains tools for direct browser control and state inspection. Key capabilities include:

• Action Execution: act (natural language instructions), computer (mouse/keyboard/screenshot), drag_drop, fill_form, and interact (natural language element finding).
• Navigation & Tabs: navigate, tabs_create, tabs_activate, tabs_close, and page_reload.
• Data Extraction: extract_data (JSON-LD, OpenGraph, etc.), page_content (HTML), read_page (Markdown/AX), and inspect.
• Network & Console: network_capture_full, network_capture_lite, request_intercept, and console_capture.
• State & Context: oc_context_export (auth-relevant state) and oc_context_import (restoring state).