SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillschrome-devtools-mcp

chrome-devtools-mcp

Testing & quality

View repository

Updated 10-15 20:11

About this skill

Chrome DevTools MCP

Use the official Chrome DevTools MCP server when Chrome DevTools context matters more than generic browser automation.

Use This Skill or Another One?

Testing job Use this skill? Why
Live logged-in Chrome session Yes Attach to the real Chrome context the user already has open
DevTools-selected element inspection Yes The selected element comes from DevTools, not generic page automation
Chrome console / network debugging Yes These are DevTools-native workflows
Lighthouse / performance / memory in Chrome Yes These require Chrome DevTools tooling
Routine Chrome form flow, screenshots, scraping No — use agent-browser Faster and simpler for Chromium automation
Firefox / WebKit / Edge / cross-browser testing No — use playwright-mcp That skill is for browser-engine coverage

Prerequisite

Install the MCP server via the repo-managed setup:

./setup.sh opencode --with-chrome-devtools-mcp
./setup.sh codex --with-chrome-devtools-mcp
./setup.sh copilot --with-chrome-devtools-mcp
./setup.sh kiro --with-chrome-devtools-mcp

Repo-managed defaults:

Mode Setup flag Result
Default --with-chrome-devtools-mcp Launches Chrome DevTools MCP with --headless and usage statistics disabled
Logged-in session (recommended) --chrome-devtools-browser-url http://127.0.0.1:9222 Attaches to a Chrome you started with --remote-debugging-port; works on any Chrome version; disables headless. Best path for auth-required testing
Logged-in via WebSocket --chrome-devtools-ws-endpoint ws://... Attaches to a Chrome WebSocket debugger endpoint
Live session (auto) --chrome-devtools-auto-connect Attaches to a running local Chrome 144+ with remote debugging enabled (more preconditions than --browser-url)
Visible browser --chrome-devtools-headed Keeps spawned Chrome visible for debugging
Narrow UI verification --chrome-devtools-slim Shrinks the tool surface to basic navigation / eval / screenshot only

The three attach modes (--chrome-devtools-browser-url, --chrome-devtools-ws-endpoint, --chrome-devtools-auto-connect) are mutually exclusive and all suppress --headless. See references/live-session.md for the full launch recipe.

If Chrome DevTools MCP is not configured for the current harness, do not improvise a replacement workflow. Tell the user the integration is not installed yet.

Server Name

Purpose MCP server name
Chrome DevTools debugging (spawns its own browser) chrome-devtools
Live attach to a logged-in Chrome (only in dual installs) chrome-devtools-live

Dual installs (--chrome-devtools-dual, and the default under --with-all-integrations) expose both servers at once. Route by task:

  • chrome-devtools — stateless, no-auth checks; the server spawns its own (headless) browser.
  • chrome-devtools-live — anything needing the user's logged-in session/cookies; attaches to a Chrome started with --remote-debugging-port (see references/live-session.md).

If only chrome-devtools exists, this is a single-server install and there is no live attach unless it was itself configured with an attach flag.

Decision Flow

Step 1 — Is this the right skill?

  • Routine open / click / fill / screenshot / scrape on Chromium → stop, use agent-browser.
  • Firefox / WebKit (Safari-class) / Edge / cross-browser → stop, use playwright-mcp.
  • Otherwise the task needs Chrome DevTools context (console, network, Lighthouse, performance, memory, a DevTools-selected element, extensions) or a logged-in Chrome session → continue.

Step 2 — Which Chrome DevTools server?

In a dual install you have two servers. Choose by whether the task needs the user's real, logged-in browser:

If the task… Use this server
needs the user's logged-in session, existing cookies, a tab they already have open, or content behind auth you cannot log into yourself chrome-devtools-live
is a fresh, no-auth check — open a URL and inspect console/network, run Lighthouse, capture a performance trace, debug memory — where a clean browser is fine chrome-devtools

Selection rules:

  • Default to chrome-devtools. Only switch to chrome-devtools-live when the task clearly depends on an authenticated or pre-existing session.
  • Phrases that mean chrome-devtools-live: "use my session", "the page I'm already on", "the logged-in dashboard", "behind the login", "my current Chrome", "the tab I have open".
  • If chrome-devtools-live is not in the tool list (single-server install), do not pretend the headless chrome-devtools is logged in. Tell the user the live/auth path isn't installed and how to enable it (./setup.sh <target> --with-chrome-devtools-mcp --chrome-devtools-dual, or a single-server --chrome-devtools-browser-url), then proceed only with what the available server can actually do.
  • If only chrome-devtools-live exists (single attach install), use it for everything; new pages open in the attached browser.

Step 3 — Confirm attachment before trusting a live session

When using chrome-devtools-live, call list_pages first. It should list the user's real tabs. If it errors or returns nothing, the user has not launched Chrome with --remote-debugging-port — point them to the recipe in references/live-session.md instead of falling back silently.

60-Second Quickstart

Fast standalone Chrome-specific check (4 calls) — server: chrome-devtools

Use this when DevTools tooling matters but you do not need the user's existing Chrome profile.

  1. new_page with the target URL
  2. take_snapshot
  3. fill_form or click with includeSnapshot: true
  4. evaluate_script or list_console_messages for the one thing you need to verify

Fast live-session check (4 calls) — server: chrome-devtools-live

Use this when the user needs their current/logged-in Chrome state. (In a single attach-only install the server is named chrome-devtools; use whichever attach server exists.)

  1. list_pages
  2. select_page
  3. take_snapshot
  4. fill_form or click with includeSnapshot: true

Use one extra call only if you still need console/network evidence after the action.

Operational Rules

  • Verify tool availability once, then stop re-enumerating tools mid-task unless a call fails with a capability error.
  • Prefer fill_form over repeated fill calls for forms.
  • Prefer includeSnapshot: true on click, fill, fill_form, hover, press_key, upload_file, and drag so you do not spend an extra turn on take_snapshot.
  • Prefer evaluate_script for deterministic state checks when the app exposes state cleanly. Use take_snapshot when you need UI structure or uids.
  • Keep snapshots non-verbose by default. Only use verbose: true when you genuinely need the full a11y tree.
  • Use file outputs for heavy assets: filePath, requestFilePath, responseFilePath, trace outputs, screenshots, and heapsnapshots.
  • Do not treat this as a generic browser-driving skill. If DevTools context stops mattering, switch to agent-browser.

Workflow Boundaries

Live Chrome / write-validation workflow

Use this only when you are intentionally validating behavior in a real Chrome session or in Chrome-specific state.

  1. Establish page context (list_pages + select_page, or new_page for a standalone run).
  2. Get the current UI anchor with take_snapshot.
  3. Perform the interaction with fill_form, click, press_key, or navigate_page, preferably with includeSnapshot: true.
  4. Confirm exactly one of:
    • resulting UI state (take_snapshot result or returned snapshot)
    • app state (evaluate_script)
    • network mutation (list_network_requests + get_network_request)
    • runtime health (list_console_messages)

Performance / Lighthouse workflow

  • Use lighthouse_audit for accessibility, SEO, best practices, and agentic browsing audits.
  • Use performance_start_trace -> performance_stop_trace -> performance_analyze_insight for performance work.
  • Treat the trace output as the source of truth for insightName and insightSetId.

Memory / extension workflow

  • Use heapsnapshot tools for memory-leak investigations.
  • Use extension tools only when the server was started with the extensions category enabled.

Live-Session Guidance

  • Repo-managed config disables usage statistics with --no-usage-statistics.
  • The default install is headless and uses a throwaway profile — it is NOT the user's logged-in browser.
  • For auth-required testing, the recommended path is --chrome-devtools-browser-url (attach to a Chrome you launched with --remote-debugging-port); --chrome-devtools-ws-endpoint and --chrome-devtools-auto-connect are alternatives. All three disable headless.
  • If the server was installed without an attach mode, do not claim you are attached to the user's existing Chrome session — you are driving a fresh headless browser.
  • See references/live-session.md for the end-to-end launch recipe.

Deep-Dive References

Reference When to Read It
references/tool-inventory.md Full tool inventory grouped by category, including slim-mode constraints
references/ui-testing-recipes.md Compact 2-4-call UI verification flows
references/performance-levers.md Speed and token-efficiency guidance for macOS and repeated runs
references/live-session.md Auto-connect, --browser-url, --ws-endpoint, and current-Chrome workflows
references/lighthouse-and-traces.md Lighthouse modes plus trace/insight analysis flows
references/troubleshooting.md Bluetooth TCC, auto-connect timeouts, sandbox, WSL, and Windows fixes

Notes

  • This skill is MCP-first. Do not switch to the chrome-devtools CLI as the default workflow.
  • --chrome-devtools-slim is only for narrow UI-verification projects. It intentionally removes most DevTools workflows.
  • Chrome DevTools MCP is Chrome-specific. Keep routine Chromium automation with agent-browser and engine coverage with playwright-mcp.