mcp-chrome-launcher
Allows Puppeteer (and Playwright) scripts to connect over CDP to the shared persistent Chrome instance at http://127.0.0.1:9223, reusing the same logged-in browser session, profile, and live tabs as the MCP agent.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-chrome-launcher open example.com and take a screenshot"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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.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.
Manual Pre-Launch Chores (or
--isolatedLogin Amnesia): Using--isolatedwipes your logins every run, while--browserUrlforces 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 |
|
|
Keeps logins, cookies & extensions | ✅ | ❌ (Wiped every run) | ✅ |
Multiple IDE windows & parallel agents | ❌ ( | ✅ (Separate browsers) | ✅ (One shared browser) |
Attach Playwright / Puppeteer / CDP scripts | ❌ (Private pipe) | ❌ (Private pipe) | ✅ ( |
Zero browser popup on IDE startup | ❌ / Varies | ❌ / Varies | ✅ (Lazy-launches on |
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@latestLocal 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
Instant Handshake: Starts
chrome-devtools-mcpimmediately over stdio soinitializeandtools/listfinish fast without opening a browser window.Lazy Launch on First
tools/call: Pausesstdinon the first tool invocation, checks if127.0.0.1:<port>is already live, and—if not—spawns a detached Chrome instance and waits until DevTools responds.Clear Conflict Diagnostics: Immediately detects and logs clear errors to
stderrif another process owns the port or an un-debugged Chrome holds the profile lock.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 numberSecurity 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 toolsclickC
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_messageARead-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_stylesARead-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_messagesBRead-only
List all console messages for the target page since the last navigation.
Inputs: pageId (required), types, pageIdx, pageSize, +3 more.
list_network_requestsARead-only
Lists the most recent requests for the target page since the last navigation.
Inputs: pageId (required), pageIdx, pageSize, resourceTypes, +1 more.
list_pagesBRead-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_insightBRead-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_pageARead-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_forARead-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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Related MCP Servers
- AlicenseBqualityDmaintenanceA 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.3215,256 npm5,681MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser through Chrome DevTools. Provides browser automation, performance analysis, debugging capabilities, and network request monitoring.2,562,190 npm57,558Apache 2.0
- AlicenseNot gradedqualityCmaintenanceShares 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.2MIT
- AlicenseNot gradedqualityBmaintenanceA local, open-source Chrome browser-automation MCP server for AI agents that controls real signed-in Chrome profiles with multi-profile routing and parallel tabs.190 npm12MIT