chrome-devtools-remote#

You are operating the chrome-devtools CLI in remote mode against a chrome-devtools-mcp server that the user has running on another host. The remote server owns the browser; your job is to drive it.

When to use this skill#

Trigger on any request that:

• Names a remote machine ("on the lab mac", "on host X", "on my tailnet box") and asks you to do something a browser would do
• Provides a chrome-devtools-mcp HTTPS URL (typically ending in /mcp) and asks for an interactive browser action
• Mentions environment variables CHROME_DEVTOOLS_MCP_REMOTE_URL or CHROME_DEVTOOLS_MCP_REMOTE_INSECURE

If the user wants to drive a local browser, use the regular chrome-devtools CLI (without --remote) or the mcp__chrome-devtools__* MCP tools instead.

Install (on the local box, once)#

The chrome-devtools client CLI ships in the same npm package as the server. Install globally on the machine where the agent runs — not on the remote host:

bash

npm install -g @vibebrowser/chrome-devtools-mcp
chrome-devtools --version   # should print 0.26.6 or newer

You do not install anything on the remote host — that host is whoever already serves https://.../mcp and is set up out-of-band.

Troubleshooting:

• command not found: chrome-devtools — npm's global bin isn't on PATH. Add $(npm config get prefix)/bin to PATH, or on macOS Homebrew add eval "$(brew shellenv)" to your shell rc.
• Cannot find package 'pkce-challenge' on first run — known bundling gap (issue dzianisv/chrome-devtools-mcp#17). Workaround: cd "$(npm root -g)/@vibebrowser/chrome-devtools-mcp" && npm install pkce-challenge --no-save.

Connect#

Configure the endpoint once per shell session and verify connectivity before doing anything else.

bash

export CHROME_DEVTOOLS_MCP_REMOTE_URL="https://lab.tailnet.ts.net/mcp"
chrome-devtools status --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

A healthy response prints status=ok http=200 plus a JSON body. Anything else is a hard stop — surface the error to the user instead of retrying.

If the URL is unset, ask the user once for the endpoint. Conventional shape: https://<host>/mcp (the /mcp path is required — the bare host returns a 404).

Connection-time flags:

SituationWhat to passSelf-signed cert (common on tailnets without Tailscale-issued certs)--insecure on every call, or export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1Bearer-token gateway--header "Authorization: Bearer $TOKEN" — repeatable, not cached, must be on every invocationCustom static header (e.g. X-Tenant: foo)--header "X-Tenant: foo"Endpoint behind Tailscale and status returns Failed to reach remote``tailscale status locally; the box is offline or the URL has the wrong hostname

Once status is green, every subsequent chrome-devtools <tool> ... --remote "$URL" call reuses the same server-side tab via a sticky session id cached at ~/.cache/chrome-devtools-mcp/remote/<hash>.session.

Session model — read this before chaining commands#

Each CLI invocation reuses a sticky session id stored under ~/.cache/chrome-devtools-mcp/remote/<hash>.session. This means:

• navigate_page → take_snapshot → click → take_screenshot all hit the same server-side tab. You can chain them as separate CLI calls and assume continuity.
• If the server restarts between calls, the next call transparently re-initializes against a fresh session. Tab state on the server is lost — re-navigate before assuming anything.
• To explicitly end the server-side session and free its browser context, run chrome-devtools stop --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL".

Common operations#

All commands accept --output-format json to return structured output you can pipe into jq.

bash

# Open a page
chrome-devtools navigate_page "https://example.com" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Get a structured a11y snapshot (use for finding clickable uids)
chrome-devtools take_snapshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL" --output-format json

# Click an element by uid from the snapshot
chrome-devtools click "$UID" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Fill an input
chrome-devtools fill "$UID" "value" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Take a screenshot (saved to /tmp/<uuid>.png locally)
chrome-devtools take_screenshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Evaluate JS in the page — return value must be JSON-serializable
chrome-devtools evaluate_script '() => document.title' --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Read console messages from the page
chrome-devtools list_console_messages --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# List network requests since page load
chrome-devtools list_network_requests --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Recipes#

Smoke-check a deployed web app#

bash

URL="$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools navigate_page "https://app.example.com" --remote "$URL"
chrome-devtools evaluate_script '() => ({title: document.title, ready: document.readyState})' --remote "$URL"
chrome-devtools list_console_messages --remote "$URL" --output-format json
chrome-devtools take_screenshot --remote "$URL"

If console_messages contains any level: "error" entries, surface them — they are usually the root cause of "the page looks broken" reports.

Drive a login form#

bash

chrome-devtools navigate_page "https://app.example.com/login" --remote "$URL"
chrome-devtools take_snapshot --remote "$URL" --output-format json > /tmp/snap.json
# Find the uid of the email input + password input + submit button from /tmp/snap.json
chrome-devtools fill "<email-uid>" "$LOGIN_EMAIL" --remote "$URL"
chrome-devtools fill "<password-uid>" "$LOGIN_PASSWORD" --remote "$URL"
chrome-devtools click "<submit-uid>" --remote "$URL"

Capture a CrUX-style trace#

bash

chrome-devtools performance_start_trace --remote "$URL"
chrome-devtools navigate_page "https://app.example.com" --remote "$URL"
chrome-devtools performance_stop_trace --remote "$URL" --output-format json

Output discipline#

• Always print the URL of the page you navigated to so the user knows which tab they're looking at.
• For screenshots, print the path of the saved file ( Saved to /tmp/<uuid>.png.) — the CLI already writes that line on stdout.
• For evaluate_script, prefer --output-format json and forward only the relevant field instead of dumping the whole structuredContent envelope.
• If the user asks "what's on the page", prefer take_snapshot over take_screenshot — the snapshot is text and cheaper to reason over.

Failure modes#

SymptomCauseFixFailed to reach remoteDNS, Tailscale offline, or wrong URLtailscale status on the local box; verify --remote URLStreamable HTTP error: ... 404 Session not foundServer restarted; sticky id was stale. Retried once internally — if you see this it means the retry also 404'dchrome-devtools stop --remote $URL to wipe the sticky pointer, then retry the commandTLS verify error ( UNABLE_TO_VERIFY_LEAF_SIGNATURE, SELF_SIGNED_CERT_IN_CHAIN)Server uses a self-signed cert (no Tailscale-issued cert)Add --insecure or export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1``Bad Request: Mcp-Session-Id header is requiredLocal cache directory was wiped mid-sessionFirst call after the wipe will mint a fresh session; just retryHangs on first call after a long idleServer idle reaper closed the sessionSame fix as the 404 row — stop then retry

Don'ts#

• Don't loop navigate_page to "wait for the page to load" — use wait_for with a text selector instead.
• Don't take_screenshot for every step in a chain — the user almost always wants one final screenshot, not five intermediate ones.
• Don't pass --insecure for a hosted endpoint with a real cert. It silently disables TLS for the whole CLI process.
• Don't try to start a server with --remote — that subcommand only manages local daemons.