Connect your coding agent to your Chrome

Recommended setup: For best results with LaunchRepo, we strongly recommend always using Claude Code CLI or Codex CLI in a terminal, rather than the Claude or Codex desktop app. This is our recommended workflow, not a guarantee of different permissions or uninterrupted execution.

Use Chrome DevTools MCP through Chrome remote debugging, with a current Node.js LTS release, npm and Google Chrome. The local dashboard saves your records; your agent controls Chrome. Start with one worker and keep its MCP connection open during the run. Do not use browser-extension transports or alternative browser-control integrations.

Choose your setup

• Chrome 144+: auto-connect works on Windows, macOS and Linux.
• macOS: review Terminal permissions.
• Auto-connect unavailable, or a separate worker needed: use a dedicated profile for macOS, Windows or Linux.
• Before submitting: perform the connection test.

Check node --version, npm --version and chrome://version. On Windows, use native Windows Node/npm and Chrome; WSL needs a separate connection setup.

Connect existing Chrome

1. In Chrome 144+, open chrome://inspect/#remote-debugging and enable remote debugging. If the control is missing, use a permitted dedicated profile below.
2. Register Chrome DevTools MCP in your agent’s MCP settings. This generic JSON example is for macOS/Linux; your agent may use a different configuration format:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics", "--no-performance-crux"]
    }
  }
}

For Windows, use "command": "cmd" and these arguments:

["/c", "npx", "-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics", "--no-performance-crux"]

3. Trigger a harmless browser action and approve Chrome’s connection prompt in the intended window. Then perform the test below.

The first invocation downloads the package. Pin a tested version after setup. See the official configuration and client setup.

Dedicated profile: choose your operating system

Run from your private workspace, outside shared/synced folders. Keep the profile ignored by Git: it contains sign-ins. Sign into the required accounts yourself. Chrome 136+ requires a nondefault profile for these debugging flags.

macOS

mkdir -p .browser/chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.browser/chrome" about:blank

Windows PowerShell

$launchrepoChrome = @(
  "$env:ProgramFiles\Google\Chrome\Application\chrome.exe",
  "${env:ProgramFiles(x86)}\Google\Chrome\Application\chrome.exe",
  "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"
) | Where-Object { Test-Path $_ } | Select-Object -First 1
if (-not $launchrepoChrome) { throw 'Locate Google Chrome first' }
New-Item -ItemType Directory -Force '.browser/chrome' | Out-Null
$launchrepoProfile = (Resolve-Path '.browser/chrome').Path
Start-Process -FilePath $launchrepoChrome -ArgumentList "--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir=`"$launchrepoProfile`" about:blank"

Linux

launchrepo_chrome=$(command -v google-chrome || command -v google-chrome-stable)
if [ -z "$launchrepo_chrome" ]; then
  echo "Install or locate Google Chrome first."
else
  mkdir -p .browser/chrome
  "$launchrepo_chrome" \
    --remote-debugging-address=127.0.0.1 \
    --remote-debugging-port=9222 \
    --user-data-dir="$PWD/.browser/chrome" about:blank
fi

Keep the launch terminal open. Replace --autoConnect in the MCP arguments with --browserUrl=http://127.0.0.1:9222; never combine them. Keep the port local and never tunnel it publicly. Check the listener: lsof -nP -iTCP:9222 -sTCP:LISTEN on macOS, ss -ltnp 'sport = :9222' on Linux, or Get-NetTCPConnection -State Listen -LocalPort 9222 | Select-Object LocalAddress, OwningProcess on Windows. Only loopback addresses are acceptable. If another program holds the port, choose an unused one and update both configurations. Never kill unrelated browsers or delete active profile locks.

macOS permissions

Check the app that launches MCP: Terminal, iTerm, or your editor/agent app. If macOS denies access to protected Chrome files:

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Add that actual host app using +, authenticate and enable it.
3. Fully quit and reopen the app, reconnect and repeat the test.

This is a permission check, not a universal CDP requirement. If the connection works, do not grant broader access unnecessarily. A CDP-only connection normally needs no Accessibility, Automation or Screen Recording permission. Chrome’s connection approval is separate and may recur after a restart.

Test the connection

Ask your agent to open https://example.com in a fresh tab, read its title and main heading, and identify its tab. Watch that window. A running MCP process alone proves nothing. Next, sign in to the target directory and confirm the actual destination identity; OAuth success alone does not prove login. Check your mailbox within its agreed permissions.

Then have the agent evaluate navigator.webdriver on that same tab. It must be false. If it is true, your MCP entry is missing --autoConnect (or --browserUrl for a dedicated profile) and Chrome DevTools MCP launched its own automation Chrome. Bot checks such as Cloudflare Turnstile then keep “verifying” forever and never show a challenge you could solve. Fix the entry, restart the agent session and repeat the test. Never hide the flag with stealth flags or scripts.

Save only pass/fail and non-sensitive notes in onboarding.json or SESSION.md. Do not copy cookies, authentication links or browser transcripts. Complete CAPTCHA/2FA yourself. After a Submit timeout, check the platform before retrying. If the wrong window moves, stop and check the connection. These instructions cannot certify your particular OS/agent combination without this test.

Two workers and window cleanup

The run planner starts with 10 submissions and one browser worker. A second worker is an advanced option you choose yourself, only after separately controlled browsers have been tested. It then needs its own platform assignment, Chrome profile, port and MCP connection. For example, use .browser/worker-1 on 9222 and .browser/worker-2 on 9223. Test each independently. If the host cannot route workers to separate connections, stay with one.

Give each submission a dedicated window. After confirmation, save its evidence and outcome, then close only that window and its owned login/verification tabs. Keep personal windows, shared inboxes, the dashboard, unsaved forms and human handoffs open. If MCP cannot close the window, close its owned tabs and record any remaining owner cleanup. Preserve the profile; reconnect if closing the last window disconnects MCP. The onboarding guide explains the next step.