chrome-devtools-remote

Original：🇺🇸 English
Translated

Drive a remote chrome-devtools-mcp server (typically on a tailnet) over HTTPS using the chrome-devtools CLI. Use this when the user wants to navigate, screenshot, inspect, or evaluate JavaScript on a browser running on another host (e.g. a Tailscale-connected Mac mini or a CI runner) — and you don't have a local Chrome to control. Examples of triggers ("open <url> on the lab mac", "take a screenshot of the browser on host X", "evaluate this on the remote browser").

10installs
Sourcedzianisv/chrome-devtools-mcp
Added on

NPX Install

npx skill4agent add dzianisv/chrome-devtools-mcp chrome-devtools-remote

Tags

Translated version includes tags in frontmatter
chrome-devtoolsremote-browser-controlcli-tooltailscale-integrationbrowser-automation

SKILL.md Content

View Translation Comparison →

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 pass
Self-signed cert (common on tailnets without Tailscale-issued certs)
--insecure
on every call, or 
export CHROME_DEVTOOLS_MCP_REMOTE_INSECURE=1
Bearer-token gateway
--header "Authorization: Bearer $TOKEN"
— repeatable, not cached, must be on every invocation
Custom 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

SymptomCauseFix
Failed to reach remote
DNS, Tailscale offline, or wrong URL
tailscale status
on the local box; verify 
--remote
URL
Streamable HTTP error: ... 404 Session not found
Server restarted; sticky id was stale. Retried once internally — if you see this it means the retry also 404'd
chrome-devtools stop --remote $URL
to wipe the sticky pointer, then retry the command
TLS 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 required
Local cache directory was wiped mid-sessionFirst call after the wipe will mint a fresh session; just retry
Hangs 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.