Setup Guide

ClawChrome lets an AI agent operate official Google Chrome through custom OS browser control. Use this guide to get from a clean setup to a connected MCP client with a persistent browser session.

Prerequisites

• Google Chrome Stable installed on the machine that will run the browser session.
• A ClawChrome install or account path from your team, the public docs, or the agent-readable setup resource.
• An MCP-capable client such as an agent harness, IDE agent, or local MCP runner.
• Permission to automate the websites and accounts involved in your workflow.

Note

ClawChrome is designed for real browsing workflows, including login-gated portals and blocked-site reliability work. You are still responsible for lawful use and for following the rules that apply to the sites and accounts you access.

Install And Set Up

Use the install path provided for your environment, then verify that the clawchrome command is available:

clawchrome --help

If you are setting up from an agent, point it at the agent-readable resource:

read https://clawchrome.com/skill.md

For a local developer setup, confirm the host can launch Chrome and that the browser profile location is writable by the user running ClawChrome.

Start A Chrome Session

Start ClawChrome with the MCP server enabled:

clawchrome start --mcp

For a workflow that should open a starting URL immediately, use the URL form supported by your installed version:

clawchrome start --url https://example.com

Keep the terminal running while your MCP client is connected. If Chrome does not appear, check that Google Chrome Stable is installed, the display is available, and no stale browser process is holding the profile lock.

Connect An MCP Client

Add ClawChrome to your MCP client using the command or endpoint printed by clawchrome start --mcp. The exact UI depends on the client, but the connection should expose browser tools for actions and observation.

After connecting, ask the client to list tools and confirm ClawChrome actions are present before sending a production workflow.

Basic Browser Actions

Most workflows can be built from five browser actions:

Action	Use it for
navigate	Open a URL in the active Chrome session.
observe	Read the current page state before deciding what to do next.
click	Select buttons, links, checkboxes, and other page controls.
type	Enter text into focused fields or a target input.
extract	Return structured information from the current page.

A typical agent loop is:

navigate to the target page
observe the page state
click or type to complete the next step
observe again
extract the result

Prefer observation and extraction over screenshot-only reasoning when the workflow can be completed from structured page state. Use visual inspection when the page layout, captcha, or target element requires it.

Session And Cookie Persistence

Persistent sessions let agents continue workflows that require login state. Use a dedicated browser profile for each sensitive workflow, and avoid sharing one profile across unrelated sites or customers.

Recommended practice:

• Create separate sessions for separate customers, accounts, or environments.
• Treat cookies and browser profiles as sensitive credentials.
• Revoke or rotate session access when a task is complete.
• Document which agent or workflow owns each persistent session.

If a site signs the browser out unexpectedly, restart the session, confirm the profile path is the same, and check whether the site invalidated the login state.

Troubleshooting

Chrome Does Not Start

Confirm Google Chrome Stable is installed and available on the host. If you are running headless infrastructure, verify that the display and window manager expected by your deployment are running.

MCP Client Cannot See Tools

Restart clawchrome start --mcp, copy the current connection details into the MCP client, and ask the client to list tools again. Some clients require a full reload after changing MCP configuration.

Clicks Or Typing Go To The Wrong Place

Make sure the Chrome window is focused and visible to the ClawChrome session. Use observe before acting so the agent can target the current page state instead of stale assumptions.

A Website Blocks Or Challenges The Session

Use a normal Chrome profile, keep session state consistent, and reduce unnecessary retries. For high-friction sites, collect the target URL, account state, challenge behavior, and agent steps before contacting support.

Next Steps

• Read the FAQ for common browser runtime and session questions.
• Review ClawChrome vs. Browserbase when comparing hosted browser sessions.
• Contact the team from Contact when a production workflow needs deployment or blocked-site review.