chrome-devtools-mcp-mux

在多个 MCP 客户端之间共享一个 Chrome 实例。每个客户端（例如单独的 Claude Code 会话）都会获得自己隔离的标签页集，同时它们都运行在同一个浏览器和配置文件上。

它解决了什么问题

chrome-devtools-mcp 将 Chrome DevTools 暴露给 MCP 客户端。它对于单个客户端运行良好，但如果两个客户端同时连接（两个 Claude Code 窗口、一个 Claude Code 加一个 Gemini CLI 等），它们会相互干扰标签页 —— list_pages 会显示所有内容，select_page 会产生竞争，new_page 会在错误的窗口中打开。

cdmcp-mux 位于客户端和 chrome-devtools-mcp 之间，为每个连接提供独立的标签页集，同时保持单个 Chrome 运行。

安装和配置（一次性）

git clone <this-repo> chrome-devtools-mcp-mux
cd chrome-devtools-mcp-mux
npm install
npm run build
npm link           # exposes `cdmcp-mux` on PATH

然后，在每个 MCP 客户端的 .mcp.json 中：

{
  "mcpServers": {
    "chrome": { "command": "cdmcp-mux" }
  }
}

就是这样。第一个连接的客户端会自动生成一个共享守护进程；后续客户端将连接到同一个守护进程。

如何验证它是否正常工作

使用上述配置启动两个 MCP 客户端。在每个客户端中，要求模型执行：

1. 通过 new_page 打开一个不同的 URL。

2. 运行 list_pages。

每个客户端应该只能看到自己的页面。在主机上，运行 cdmcp-mux status 以在守护进程中并排查看两个上下文。

有关带有录制视频的完整脚本演示，请参阅 demo/。

环境变量（可选）

调试

所有内容均为带外（out-of-band）；多路复用器从不向 MCP 客户端暴露调试工具。

日志位于 ~/.local/state/cdmcp-mux/mux.log。

工作原理

flowchart TB
    subgraph clients["one process per MCP client"]
      direction LR
      C1["Claude Code #1"] -- "stdio (MCP)" --> S1["cdmcp-mux shim"]
      C2["Claude Code #2"] -- "stdio (MCP)" --> S2["cdmcp-mux shim"]
    end

    subgraph shared["shared — auto-spawned on first connect"]
      direction TB
      D["mux daemon<br/><i>per-connection context table</i><br/>(socket fd → ctxId → owned pageIds)"]
      U["chrome-devtools-mcp subprocess<br/><code>--experimentalPageIdRouting</code><br/><code>--userDataDir <fixed></code>"]
      B["Chromium<br/><i>one instance, one profile</i>"]
      D -- "stdio (MCP)<br/>rewrite + filter" --> U
      U -- "CDP" --> B
    end

    S1 -- "unix socket" --> D
    S2 -- "unix socket" --> D

    classDef client fill:#e3f2fd,stroke:#1976d2
    classDef shim fill:#fff3e0,stroke:#f57c00
    classDef core fill:#f3e5f5,stroke:#7b1fa2
    classDef browser fill:#e8f5e9,stroke:#388e3c
    class C1,C2 client
    class S1,S2 shim
    class D,U core
    class B browser

每个 MCP 客户端都会生成自己的 cdmcp-mux 垫片（这就是 .mcp.json 的工作方式 —— 每个客户端一个子进程）。该垫片是客户端 stdio 和 unix 套接字之间的纯字节管道；第一个连接的垫片会自动生成共享守护进程，后续垫片连接到它。守护进程拥有 一个 chrome-devtools-mcp 子进程，驱动 一个 带有 一个 --userDataDir 的 Chromium。

每个 unix 套接字连接 = 一个全新的 BrowserContext（隔离的 cookie、localStorage、WebSockets）。守护进程通告与原生 chrome-devtools-mcp 完全相同的工具模式 —— pageId 和 isolatedContext 会从客户端看到的内容中剥离，并在守护进程的每个连接所有权表中的每次 tools/call 上重新注入。原子性使用上游的 --experimentalPageIdRouting，因此来自不同上下文的并发调用不会相互覆盖。当客户端断开连接时，其标签页会被关闭，其浏览器上下文会被销毁。

开发笔记

本项目由 Claude-Code 代理在单个工作会话中从头到尾编写，由实时对话需求驱动。完整的测试计划按功能正确性分层（58 个测试，约 19 秒，全部通过），并且多路复用器随后通过 VNC 自动化复现器进行了视觉演示。

有关 PRD 到测试的映射，请参阅 DEMO.md。有关完整的代理开发日志（需求发现、架构迭代、测试分层以及视频演示的三个版本），请参阅 demo/README.md。

测试

# requires a Chromium binary; the smoke/e2e tests need it
CDMCP_MUX_CHROMIUM=/usr/bin/chromium npm test

预期：8 个文件，58 个测试，全部通过。

发布

CI 在每次推送到 main 分支和 PR 时运行，使用 Node 22 和 24 进行构建、类型检查并执行完整的 58 项测试套件（包括真实的 Chromium 冒烟测试和二进制 e2e 测试）。

发布通过 .github/workflows/publish.yml 自动化，该工作流在 GitHub 发布版本时运行：

1. 增加 package.json 中的 version，提交并标记为 v<version>。

2. gh release create v<version> --generate-notes。

3. 工作流构建、测试并运行 npm publish，带有 npm 来源证明（通过 GitHub OIDC 签名，工作流具有 id-token: write 权限）。

NPM_TOKEN 是唯一必需的仓库密钥。该包发布时带有 publishConfig.provenance: true，因此 --provenance 标志是隐式的。一旦此仓库在 npmjs.com 上注册为 受信任的发布者，就可以完全移除 NPM_TOKEN 密钥。

许可证

Apache-2.0 — 参见 LICENSE。与上游 chrome-devtools-mcp 相同。