chrome-devtools-mcp-wrapper

Session-local Chrome launcher for Chrome DevTools MCP workflows.

• Repository: https://github.com/mjwyr/chrome-devtools-mcp-canpoint.git
• Author: 若清风

This wrapper gives each MCP server process its own random remote debugging port and generated user data directory, so multiple agent sessions do not fight over port 9222 or a shared Chrome profile. By default, the actual Chrome process is started lazily: normal MCP startup and tool discovery can complete without opening a browser. In lazy mode the wrapper answers tools/list from the official chrome-devtools-mcp package metadata, then launches Chrome only when the conversation first calls a browser-backed MCP tool. On Windows it also resolves common command shims such as npx.cmd, so downstream MCP commands can be passed as normal argument lists.

Official MCP compatibility

Wrapper 1.2.0 is verified against official chrome-devtools-mcp 1.10.1 (latest stable checked on 2026-10-15). The bundled fallback contains the 30 default official tools, including get_css_styles, current page-ID routing, multi-file uploads, and console stack traces. Normal discovery reads the actual downstream package, including tools enabled through CLI flags or a JSON config. See upgrade notes and feature options.

Official options go after chrome-devtools-mcp@latest; wrapper options go before --. For example, enable the additional heap analysis tools:

uvx chrome-devtools-mcp-wrapper -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url} --memory-debugging

Use chrome-devtools-mcp@1.10.1 in place of @latest to pin the verified release. Official Node.js requirements are ^20.19.0 || ^22.12.0 || >=23.

If live discovery fails, default configurations can use the bundled snapshot. For custom tool settings, JSON config files, or a different pinned upstream version, the wrapper requests the real downstream tool list instead. In this failure case Chrome may start during discovery, so that the advertised tools still match the configured server.

Usage

Two distribution channels are available:

Registry	Package	Runtime
PyPI	chrome-devtools-mcp-wrapper	Python 3.10+ (managed by uvx)
npm	chrome-devtools-mcp-canpoint	Node.js + uv/uvx; launches the same-version PyPI package

The npm name differs because chrome-devtools-mcp-wrapper on npm is an unrelated package owned by another author.

Run it directly with uvx:

uvx chrome-devtools-mcp-wrapper -- <downstream-mcp-command>

Example:

uvx chrome-devtools-mcp-wrapper -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Equivalent npm entry point:

npx -y chrome-devtools-mcp-canpoint@latest -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

By default, Chrome starts in lazy mode and uses quiet window startup once a browser-backed tool is called. Quiet mode keeps Chrome headful for compatibility, adds --start-minimized, and uses a best-effort non-activating minimized startup on Windows. It reduces focus stealing but cannot guarantee Chrome or the OS will never focus the window.

Preserve the old startup-time launch behavior with:

uvx chrome-devtools-mcp-wrapper --launch-mode eager -- <downstream-mcp-command>

Force a fully headless browser with either option:

uvx chrome-devtools-mcp-wrapper --window-mode headless -- <downstream-mcp-command>
uvx chrome-devtools-mcp-wrapper --headless -- <downstream-mcp-command>

If Chrome is not installed in the default Windows location, pass it explicitly:

uvx chrome-devtools-mcp-wrapper --chrome-path "D:\Apps\Chrome\chrome.exe" -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

PWA tools and pipe connections

Use --connection-mode pipe to let the official MCP launch Chrome over a CDP pipe, enabling the PWA tools:

uvx chrome-devtools-mcp-wrapper --connection-mode pipe -- npx -y chrome-devtools-mcp@latest --category-pwa
npx -y chrome-devtools-mcp-canpoint@latest --connection-mode pipe -- npx -y chrome-devtools-mcp@latest --category-pwa

This exposes install_pwa, launch_pwa, get_os_app_state, and uninstall_pwa. The wrapper prepares a separate session profile on the first tool call and cleans it up on exit. Windows process jobs also track the downstream process tree, including Chrome. Pipe mode allocates no remote debugging port.

Do not pass downstream --browser-url, --ws-endpoint, --auto-connect, --user-data-dir, --executable-path, --isolated, or --channel, including in the official JSON config. Put browser/profile settings before -- instead. --profile-mode copy is supported; --profile-mode inherit is rejected to avoid using the personal browser profile as the pipe-owned session.

For example, specify Chrome and a dedicated persistent app profile:

uvx chrome-devtools-mcp-wrapper --connection-mode pipe --chrome-path "C:\Program Files\Google\Chrome\Application\chrome.exe" --user-data-dir "C:\work\pwa-profile" -- npx -y chrome-devtools-mcp@latest --category-pwa

PWA installation can create OS integrations such as shortcuts. For temporary tests, call uninstall_pwa before ending the session; deleting a browser profile does not substitute for uninstalling the app. --keep-profile retains a generated profile, and an explicit --user-data-dir is never deleted by the wrapper. Quiet startup in pipe mode uses Chrome's --start-minimized flag and is best effort. --launch-mode eager starts the downstream MCP immediately; the official MCP still starts its browser on the first browser tool call.

Codex MCP Config

After publishing to PyPI, configure Codex like this:

[mcp_servers.chrome-devtools]
command = "uvx"
args = [
  "chrome-devtools-mcp-wrapper",
  "--",
  "npx",
  "-y",
  "chrome-devtools-mcp@latest",
  "--browser-url={browser_url}",
  "--no-usage-statistics"
]
startup_timeout_sec = 60

Claude Code MCP Config

Claude Code stores global MCP server entries in ~/.claude.json under mcpServers. A matching entry looks like this:

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "chrome-devtools-mcp-wrapper",
        "--",
        "npx",
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url={browser_url}"
      ],
      "env": {}
    }
  }
}

Add it from PowerShell to avoid Git Bash/MSYS path conversion changing /c-style arguments:

claude mcp add chrome-devtools -- uvx chrome-devtools-mcp-wrapper -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

For older wrapper versions that do not resolve Windows command shims, use the temporary workaround below. It should not be needed after this package version is installed:

claude mcp add chrome-devtools -- uvx chrome-devtools-mcp-wrapper -- cmd /c npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Session Profile Directory

By default, generated Chrome profiles are created under:

<current-working-directory>/.chrome-mcp-sessions/<uuid>

Override the parent directory with --session-root:

uvx chrome-devtools-mcp-wrapper --session-root .\.chrome-mcp-sessions -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Use --user-data-dir only when you want an exact profile directory instead of a generated per-session subdirectory.

Chrome Profile Modes

The default profile mode is isolated. It creates a fresh project-local Chrome profile for each MCP session and deletes it when the downstream MCP exits. This keeps concurrent agent sessions from sharing ports, cookies, locks, or profile state.

Use inherit when you explicitly want the MCP-controlled Chrome to use an existing local Chrome user data directory directly:

uvx chrome-devtools-mcp-wrapper --profile-mode inherit -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

By default, the source user data directory is detected from the local platform:

• Windows: %LOCALAPPDATA%\Google\Chrome\User Data
• macOS: ~/Library/Application Support/Google/Chrome
• Linux: ~/.config/google-chrome

Override detection or select a non-default profile with:

uvx chrome-devtools-mcp-wrapper --profile-mode inherit --source-user-data-dir "C:\Users\me\AppData\Local\Google\Chrome\User Data" --source-profile "Profile 1" -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Use copy when you want a generated session profile prefilled from an existing Chrome profile:

uvx chrome-devtools-mcp-wrapper --profile-mode copy --source-profile "Default" -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Safe copy mode includes regular profile files such as bookmarks and preferences, but excludes caches, lock files, cookies, sessions, web data, and saved-login databases. To copy those sensitive databases too, opt in explicitly:

uvx chrome-devtools-mcp-wrapper --profile-mode copy --include-sensitive-profile-data -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Security notes:

• inherit exposes the real Chrome profile, including cookies, sessions, saved passwords, and browsing state, to the downstream MCP process.
• inherit can conflict with an already running Chrome instance that uses the same user data directory.
• copy --include-sensitive-profile-data copies sensitive databases into the temporary session profile, but Chrome encryption may still prevent copied passwords or cookies from being usable in the new session.
• Copied temporary profiles are deleted after exit unless --keep-profile is set.

Environment Passed to the Downstream MCP

The downstream command receives these variables:

• CHROME_DEVTOOLS_URL: http://127.0.0.1:<random-port>
• BROWSER_URL: same value as CHROME_DEVTOOLS_URL
• CHROME_REMOTE_DEBUGGING_PORT: selected port
• CHROME_USER_DATA_DIR: session profile path

Configure the real Chrome MCP package to use one of these values as its browser endpoint. This wrapper also expands placeholders in downstream command arguments:

• {browser_url} or {devtools_url}: http://127.0.0.1:<random-port>
• {port}: selected port
• {user_data_dir}: generated profile path

Cleanup

When the downstream MCP exits, stdin closes, Ctrl+C is received, or the MCP client closes the session, this wrapper terminates only the Chrome process it started. If lazy mode never needed Chrome, no browser process is started. On Windows, Chrome is also assigned to a Job Object with KILL_ON_JOB_CLOSE, so the browser is cleaned up when the wrapper process exits unexpectedly in normal session-shutdown paths. Temporary profiles are deleted by default after they have actually been materialized.

A forced process kill that prevents Windows or Python cleanup from running can still leave Chrome behind; restart the MCP client or close that Chrome process if that happens.

Use --keep-profile when debugging:

uvx chrome-devtools-mcp-wrapper --keep-profile -- npx -y chrome-devtools-mcp@latest --browser-url={browser_url}

Options

uvx chrome-devtools-mcp-wrapper --help

Useful options:

• --chrome-path: path to Chrome; defaults to CHROME_PATH or common install paths
• --profile-mode: isolated, inherit, or copy; defaults to isolated
• --source-user-data-dir: Chrome user data root for inherit or copy
• --source-profile: Chrome profile directory name, default Default
• --include-sensitive-profile-data: include cookies, sessions, and saved-login databases in copy mode
• --session-root: parent directory for generated project-local profiles
• --user-data-dir: explicit profile directory instead of a generated one
• --keep-profile: leave the temporary profile on disk
• --launch-mode: lazy (default) or eager
• --window-mode: quiet (default), visible, or headless
• --headless: backward-compatible alias for --window-mode headless
• --chrome-arg: pass extra arguments to Chrome, repeatable
• --devtools-timeout: seconds to wait for /json/version

Development

Use the project virtual environment for local development:

.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m unittest discover -v
.\.venv\Scripts\chrome-devtools-mcp-wrapper.exe --help

Build distributions:

.\.venv\Scripts\python.exe -m build

Acknowledgments

This project is promoted through the open-source promotion program of the LINUX DO community. Thanks to LINUX DO for providing an open and friendly environment for sharing open-source projects.