Chrome Devtools Wrapper

npm chrome-devtools-mcp-wrapper package

A dynamic multi-browser wrapper around chrome-devtools-mcp that lets your AI coding agent connect to multiple Chrome instances at once and switch between them at runtime — without restarting the MCP server.

Implements the feature proposed in ChromeDevTools/chrome-devtools-mcp#590.

Key features

• Dynamic browser routing: connect to any number of Chrome instances and route each tool call to the right one via an optional browserUrl argument.
• Runtime switching: call switch_browser to change the active browser without restarting anything.
• All upstream tools included: every tool from chrome-devtools-mcp is proxied automatically, plus two wrapper-native tools (switch_browser, list_browsers).
• No fork: runs npx chrome-devtools-mcp@latest as a subprocess, so upstream updates are picked up automatically.

Getting started

Add the following config to your MCP client:

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

To connect to an already-running Chrome instance at startup:

{
  "mcpServers": {
    "chrome-devtools-wrapper": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp-wrapper@latest", "--browser-url=http://127.0.0.1:9222"]
    }
  }
}

[!NOTE] Using chrome-devtools-mcp-wrapper@latest ensures your MCP client always uses the latest version.

MCP client configuration

claude mcp add chrome-devtools-wrapper --scope user -- npx -y chrome-devtools-mcp-wrapper@latest

code --add-mcp '{"name":"chrome-devtools-wrapper","command":"npx","args":["-y","chrome-devtools-mcp-wrapper@latest"],"env":{}}'

code --add-mcp '{"""name""":"""chrome-devtools-wrapper""","""command""":"""npx""","""args""":["""-y""","""chrome-devtools-mcp-wrapper@latest"""]}'

gemini mcp add chrome-devtools-wrapper npx chrome-devtools-mcp-wrapper@latest

gemini mcp add -s user chrome-devtools-wrapper npx chrome-devtools-mcp-wrapper@latest

[mcp_servers.chrome-devtools-wrapper]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp-wrapper@latest"]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

Requirements

• Node.js LTS version (20.19+ or 22.12+)
• Chrome current stable version or newer
• npm

Usage

1. Start Chrome with remote debugging

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile

Linux

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile

Windows

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile"

[!WARNING] Enabling the remote debugging port exposes a debugging interface that any local application can connect to. Avoid browsing sensitive websites while the port is open.

2. Connect to your browser

switch_browser(url: "9222")

Or with a full URL or WebSocket endpoint:

switch_browser(url: "http://127.0.0.1:9222")
switch_browser(url: "ws://127.0.0.1:9222/devtools/browser/abc123")

After connecting, all chrome-devtools-mcp tools become available.

3. Use any browser tool

navigate_page(url: "https://example.com")
take_screenshot()
evaluate_script(expression: "document.title")

4. Route a single call to a specific browser

Every proxied tool accepts an optional browserUrl argument:

navigate_page(url: "https://staging.example.com", browserUrl: "9333")
take_screenshot(browserUrl: "9222")

5. Check active connections

list_browsers()

Wrapper-native tools

These two tools are always available, even before a browser connects:

All other tools come from chrome-devtools-mcp and are registered once a browser connects.

Configuration options

WebSocket endpoint

If you know the exact WebSocket endpoint (from http://127.0.0.1:9222/json/version → webSocketDebuggerUrl):

{
  "mcpServers": {
    "chrome-devtools-wrapper": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp-wrapper@latest",
        "--browser-url=ws://127.0.0.1:9222/devtools/browser/<id>"
      ]
    }
  }
}

Multiple browsers

Start multiple Chrome instances on different ports, then route calls dynamically:

switch_browser(url: "9222")
navigate_page(url: "https://prod.example.com")

navigate_page(url: "https://staging.example.com", browserUrl: "9333")
take_screenshot(browserUrl: "9333")

How it works

MCP client (Claude Code, Cursor, etc.)
    │
    ▼
chrome-devtools-mcp-wrapper
    ├── switch_browser / list_browsers  ← always available
    ├── navigate_page(browserUrl?)      ─┐
    ├── take_screenshot(browserUrl?)     ├─ proxied from chrome-devtools-mcp
    ├── evaluate_script(browserUrl?)     │  registered after first browser connects
    └── ... (50+ tools)                 ─┘
         │                    │
         ▼                    ▼
  backend [9222]        backend [9333]
  npx chrome-           npx chrome-
  devtools-mcp          devtools-mcp
  --browserUrl=         --browserUrl=
  ...9222               ...9333

• One chrome-devtools-mcp subprocess per browser URL, reused across calls
• Idle backends are killed after 5 minutes of inactivity
• Upstream updates are inherited automatically on restart

Relation to upstream

This package wraps chrome-devtools-mcp without forking it. All 50+ upstream tools are proxied transparently.

For single-browser use cases, the upstream package is the right choice. Use this wrapper when you need to connect to multiple Chrome instances or switch between them at runtime.