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을 실행하면서도 각 연결에 격리된 탭 세트를 제공합니다.

설치 및 구성 (1회)

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)에서 처리됩니다. mux는 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 심(shim)을 생성합니다(이것이 .mcp.json이 작동하는 방식입니다. 클라이언트당 자식 프로세스 하나). 심은 클라이언트의 stdio와 유닉스 소켓 사이의 순수 바이트 파이프입니다. 연결된 첫 번째 심이 공유 데몬을 자동으로 생성하고, 이후 심들은 여기에 연결됩니다. 데몬은 하나의 --userDataDir을 사용하는 하나의 Chromium을 구동하는 하나의 chrome-devtools-mcp 하위 프로세스를 소유합니다.

모든 유닉스 소켓 연결은 하나의 새로운 BrowserContext(격리된 쿠키, 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 files, 58 tests, all passing.

릴리스

CI는 Node 22 및 24를 사용하여 main 브랜치에 대한 모든 푸시 및 PR 시 실행되며, 빌드, 타입 체크 및 전체 58개 테스트 스위트(실제 Chromium 스모크 테스트 및 바이너리 e2e 테스트 포함)를 실행합니다.

게시는 GitHub 릴리스가 게시될 때 실행되는 .github/workflows/publish.yml을 통해 자동화됩니다:

1. package.json의 version을 올리고 커밋한 후 v<version>으로 태그를 지정합니다.

2. gh release create v<version> --generate-notes를 실행합니다.

3. 워크플로우는 빌드, 테스트를 수행하고 npm provenance와 함께 npm publish를 실행합니다(GitHub OIDC를 통해 서명, 워크플로우에 id-token: write 권한 필요).

NPM_TOKEN은 유일하게 필요한 리포지토리 시크릿입니다. 패키지는 publishConfig.provenance: true로 게시되므로 --provenance 플래그가 암시적으로 적용됩니다. 이 리포지토리가 npmjs.com에 **신뢰할 수 있는 게시자(trusted publisher)**로 등록되면 NPM_TOKEN 시크릿을 완전히 제거할 수 있습니다.

라이선스

Apache-2.0 — LICENSE를 참조하세요. 업스트림 chrome-devtools-mcp와 동일합니다.