Skip to main content
Glama

mcp-chrome-launcher

One persistent, logged-in Chrome shared across all your AI agents, IDE windows, and Playwright/Puppeteer scripts—launched lazily on demand.

Zero runtime dependencies • Cross-platform (Windows, macOS, Linux) • 100% Test Coverage • Drop-in replacement for chrome-devtools-mcp


Why This Exists

By default, Google's chrome-devtools-mcp launches Chrome over a private pipe (--remote-debugging-pipe) and locks the user profile directory. That creates three daily headaches:

  1. Multi-Window & Sub-Agent Crashes (SingletonLock): Opening a second Cursor/VS Code workspace or running parallel Claude Code sessions crashes because the first MCP process locked the profile.

  2. Playwright & Puppeteer Lockout: Because the pipe is private to the MCP process, your own Playwright, Puppeteer, or custom CDP scripts cannot attach to the same logged-in browser.

  3. Manual Pre-Launch Chores (or --isolated Login Amnesia): Using --isolated wipes your logins every run, while --browserUrl forces you to manually boot Chrome with special flags from a terminal before opening your IDE.

mcp-chrome-launcher fixes all three automatically. Drop it in place of chrome-devtools-mcp—it stays completely invisible on IDE startup, lazy-launches one detached Chrome on 127.0.0.1:9223 the moment a browser tool is actually called, and connects every MCP client and external script to that single warm, logged-in session.

Capability

Default chrome-devtools-mcp

chrome-devtools-mcp --isolated

mcp-chrome-launcher

Keeps logins, cookies & extensions

✅

❌ (Wiped every run)

✅

Multiple IDE windows & parallel agents

❌ (SingletonLock crash)

✅ (Separate browsers)

✅ (One shared browser)

Attach Playwright / Puppeteer / CDP scripts

❌ (Private pipe)

❌ (Private pipe)

✅ (http://127.0.0.1:9223)

Zero browser popup on IDE startup

❌ / Varies

❌ / Varies

✅ (Lazy-launches on tools/call)

Survives IDE / agent restarts

❌

❌

✅ (Detached process)


Related MCP server: Chrome DevTools MCP

Quick Start (Drop-In Replacement)

Replace chrome-devtools-mcp with mcp-chrome-launcher in your MCP config (claude_desktop_config.json, .cursor/mcp.json, Windsurf, Gemini CLI, etc.). Any extra flags pass straight through to chrome-devtools-mcp!

(Before first run: close any existing Chrome window already holding ~/.chrome-dev-profile without remote debugging.)

Via npx (Recommended)

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-chrome-launcher@latest"
      ]
    }
  }
}

Claude Code CLI (One-Liner)

claude mcp add chrome-devtools -- npx -y mcp-chrome-launcher@latest

Local Clone / Custom Flags

Any unrecognized flags (like --categoryExtensions) forward directly to chrome-devtools-mcp:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": [
        "/path/to/mcp-chrome-launcher/mcp-chrome-launcher.mjs",
        "--port=9223",
        "--allowUnrestrictedPaths",
        "--categoryExtensions"
      ]
    }
  }
}

Bonus: Attach Playwright or Puppeteer to the Same Browser

Because Chrome exposes its DevTools endpoint locally on 127.0.0.1:9223, your own E2E scripts or scrapers can jump right into the exact browser session your AI agent is driving:

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP('http://127.0.0.1:9223');
const context = browser.contexts()[0];
const page = context.pages()[0];
console.log('Sharing live tab with MCP:', await page.title());

How It Works

  1. Instant Handshake: Starts chrome-devtools-mcp immediately over stdio so initialize and tools/list finish fast without opening a browser window.

  2. Lazy Launch on First tools/call: Pauses stdin on the first tool invocation, checks if 127.0.0.1:<port> is already live, and—if not—spawns a detached Chrome instance and waits until DevTools responds.

  3. Clear Conflict Diagnostics: Immediately detects and logs clear errors to stderr if another process owns the port or an un-debugged Chrome holds the profile lock.

  4. Cross-Platform Discovery: Automatically locates Chrome/Chromium on Windows, macOS, and Linux (or accepts --chromePath).


CLI Options

Usage: mcp-chrome-launcher [options] [chrome-devtools-mcp-args...]

Options:
  --port <port>           Remote debugging port (default: 9223)
  --userDataDir <path>    Chrome user data directory (default: ~/.chrome-dev-profile)
  --chromePath <path>     Path to Chrome executable (default: auto-detected)
  -h, --help              Show this help message
  -v, --version           Show version number

Security Note

Chrome is intentionally spawned detached and bound strictly to loopback (127.0.0.1:<port>) so subsequent agent sessions and local scripts can reuse your warm tabs. Any local process on your machine can connect to 127.0.0.1:<port> while that browser window stays open—quit that Chrome window when finished to close the debug port.

Available Tools

33 tools
clickC

Clicks on the provided element

Inputs: uid (required), pageId (required), dblClick, includeSnapshot.

close_pageB

Closes the page by its index. The last open page cannot be closed.

Inputs: pageId (required).

dragC

Drag an element onto another element

Inputs: pageId (required), to_uid (required), from_uid (required), includeSnapshot.

emulateA

Emulates various features on the target page. Each call replaces all emulation settings (except extraHttpHeaders), so pass all desired settings in a single call.

Inputs: pageId (required), viewport, userAgent, colorScheme, +7 more.

evaluate_scriptB

Evaluate JavaScript inside the target page. The source can be provided inline or loaded from a local file. Returns the response as JSON, so returned values have to be JSON-serializable.

Inputs: pageId (required), args, format, filePath, +4 more.

fillB

Type text into an input, text area or select an option from a element.

Inputs: uid (required), value (required), pageId (required), includeSnapshot.

fill_formA

Fill out multiple form elements (inputs, selects, checkboxes, radios) at once. ALWAYS prefer this tool over multiple individual 'fill' or 'click' calls when interacting with forms. It is significantly faster, more reliable, and reduces turn count. Example: Fill username, password, and check "Remember Me" in one call.

Inputs: pageId (required), elements (required), includeSnapshot.

get_console_messageA
Read-only

Gets a console message by its ID. You can get all messages by calling list_console_messages.

Inputs: msgid (required), pageId (required).

get_css_stylesA
Read-only

Retrieve matched CSS rules, inline styles (element.style), inherited styles, custom properties, and cascade wrappers (@layer, @media, @container, @scope) for an element identified by its UID. Rules are ordered from highest to lowest cascade precedence and include source line numbers (e.g. index:196). Active (winning) declarations have no prefix tag, while (losing) overridden declarations are prefixed with [overloaded]. Treat the output as authoritative and complete. Results are paginated (10 rules per page by default); use pageIdx to page through the remaining rules. Requires a UID from take_snapshot.

Inputs: uid (required), pageId (required), pageIdx, pageSize.

get_network_requestA

Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel. Useful for inspecting request headers (including 'Cookie') and response headers (including 'Set-Cookie' and directives).

Inputs: pageId (required), reqid, requestFilePath, responseFilePath.

handle_dialogC

If a browser dialog was opened, use this command to handle it

Inputs: action (required), pageId (required), promptText.

hoverC

Hover over the provided element

Inputs: uid (required), pageId (required), includeSnapshot.

lighthouse_auditA

Get Lighthouse scores, failing audits, and the DOM nodes they flag for accessibility, SEO, best practices, and agentic browsing. Full reports are saved to disk. This excludes performance. For performance audits, run performance_start_trace

Inputs: pageId (required), mode, device, outputDirPath.

list_console_messagesB
Read-only

List all console messages for the target page since the last navigation.

Inputs: pageId (required), types, pageIdx, pageSize, +3 more.

list_network_requestsA
Read-only

Lists the most recent requests for the target page since the last navigation.

Inputs: pageId (required), pageIdx, pageSize, resourceTypes, +1 more.

list_pagesB
Read-only

Get a list of pages open in the browser.

Inputs: no named parameters.

new_pageC

Open a new tab and load a URL. Use project URL if not specified otherwise.

Inputs: url (required), timeout, background, isolatedContext.

performance_analyze_insightB
Read-only

Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.

Inputs: pageId (required), insightName (required), insightSetId (required).

performance_start_traceA

Start a performance trace on the target webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.

Inputs: pageId (required), reload, autoStop, filePath, +1 more.

performance_stop_traceB

Stop the active performance trace recording on the target webpage.

Inputs: pageId (required), filePath.

press_keyA

Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations). Note: On macOS, native elements cannot be operated with ArrowDown/Enter via press_key; use fill() on the combobox or click() on the option instead.

Inputs: key (required), pageId (required), includeSnapshot.

resize_pageC

Resizes the page's window so that the page has specified dimension

Inputs: width (required), height (required), pageId (required).

screencast_startC

Starts recording a screencast (video) of the target page.

Inputs: pageId (required), filePath.

screencast_stopB

Stops the active screencast recording on the target page.

Inputs: pageId (required).

select_pageA
Read-only

Select a page as a context for future tool calls.

Inputs: pageId (required), bringToFront.

set_logpointsA

Set the complete set of logpoints of the selected page: logpoints not in the list are removed, new ones are added, and an empty list removes all. A logpoint logs expressions to the console every time a line executes, without pausing or changing the source, like logpoints in the DevTools Sources panel. Locations are script URLs or original source files resolved through source maps (not available with --no-source-maps; scripts in workers and out-of-process iframes are not supported). A location in a generated script moves to its original source line when a source map covers it, and locations on the same line become one logpoint with the last expression. Output appears in list_console_messages; an expression that throws produces an error message without text. Logpoints survive reloads and navigations until removed or the page is closed. The response lists the resulting logpoints and where they are bound.

Inputs: pageId (required), logpoints (required).

take_heapsnapshotA

Capture a heap snapshot of the target page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.

Inputs: pageId (required), filePath (required).

take_screenshotC

Take a screenshot of the page or element.

Inputs: pageId (required), uid, format, quality, +2 more.

take_snapshotA

Take a text snapshot of the target page based on the a11y tree. The snapshot lists page elements along with a unique identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected in the DevTools Elements panel (if any).

Inputs: pageId (required), verbose, filePath.

type_textA

Type text using keyboard into a previously focused input

Inputs: text (required), pageId (required), submitKey.

upload_fileC

Upload a file through a provided element.

Inputs: uid (required), pageId (required), filePaths (required), includeSnapshot.

wait_forA
Read-only

Wait for the specified text to appear on the selected page. By default, hidden text is also matched. Set visible to true to wait until the matched text is visible.

Inputs: text (required), pageId (required), timeout, visible.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 33 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or actions (navigation, page lifecycle, console, network, performance, memory). The main overlap is among input tools—type_text, fill, fill_form, and press_key—where an agent could misselect despite the descriptions clarifying intended use cases. Screenshot/snapshot/screencast tools are also somewhat adjacent but distinguishable.

    Naming Consistency4/5

    The surface is overwhelmingly snake_case and readable, but conventions vary: most tools use verb_noun (list_pages, navigate_page), several domain tools use noun_verb (performance_start_trace, screencast_start), and some are bare verbs (click, drag, hover, fill). These deviations are minor and predictable within domains, but not fully uniform.

    Tool Count3/5

    At 33 tools the surface is heavy, though the Chrome automation/DevTools domain is inherently broad. Many tools are specialized and earn their place (performance tracing, heap snapshot, logpoints, lighthouse, CSS inspection), but the overall count is on the high end and may overwhelm routine agent workflows.

    Completeness4/5

    Coverage is strong across page lifecycle, navigation, input, forms, dialogs, uploads, screenshots/snapshots, console, network, performance, memory, CSS, emulation, and logpoints. Minor gaps remain around browser storage/cookies, direct DOM/HTML retrieval, and network interception, but most core workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides browser automation capabilities using Playwright. This server enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment.
      32
      15,256 npm
      5,681
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Shares one Chrome browser across multiple AI coding sessions via an MCP proxy, adding lifecycle management, tool filtering, and anti-detection while wrapping the upstream chrome-devtools-mcp server.
      2
      MIT