Chrome MCP

Chrome MCP는 브라우저 세션을 다른 엔진으로 복사하지 않고 실제 Chrome 탭을 Model Context Protocol 클라이언트에 노출합니다. Chrome 확장 프로그램은 chrome.debugger를 통해 사용자의 기존 프로필에 있는 탭을 제어하며, 상주하는 로컬 데몬은 하나 이상의 Chrome 프로필과 MCP 프로세스를 조정합니다.

아키텍처

MCP client ──stdio── MCP bridge ──authenticated HTTP── persistent daemon
                                                        │
                                                        ├── WebSocket ── Chrome extension/profile A ── tabs
                                                        └── WebSocket ── Chrome extension/profile B ── tabs

• 탭은 브라우저 세션입니다. 세션을 닫으면 해당 Chrome 탭이 닫힙니다.

• 각 확장 프로그램 설치는 하나의 Chrome 프로필/인스턴스를 나타냅니다.

• 데몬은 연결된 모든 인스턴스에 걸쳐 전역 숫자 session_id 값을 할당합니다.

• 데몬은 MCP 클라이언트가 재시작되어도 독립적으로 유지되며 트레이 아이콘이 없습니다.

• 작업은 chrome.debugger를 통해 Chrome DevTools Protocol을 사용하므로 평가된 JavaScript가 페이지 CSP에 의해 차단되지 않습니다.

• 세션 마이그레이션이 필요 없으므로 인증 상태, 쿠키, IndexedDB, 서비스 워커, 인증서, 확장 프로그램, 브라우저 지문이 원래 Chrome 프로필에 그대로 유지됩니다.

Related MCP server: monkeysee

설치

Chrome 116 이상이 필요합니다.

bun install

사용 가능하게 할 모든 Chrome 프로필에 확장 프로그램을 로드합니다:

1. chrome://extensions를 엽니다.

2. 개발자 모드를 활성화합니다.

3. 압축 해제된 확장 프로그램 로드를 선택합니다.

4. 이 저장소의 extension 디렉터리를 선택합니다.

5. 확장 프로그램 팝업을 열고 인스턴스에 알아보기 쉬운 이름을 지정한 다음, 적절한 경우 기본값으로 사용을 선택합니다.

Chrome은 ws://127.0.0.1:55333에 연결할 수 있어야 합니다. 데몬은 chrome-extension:// 출처에서만 확장 프로그램 WebSocket을 수락하며 localhost에만 바인딩합니다.

MCP 클라이언트 구성

{
  "mcpServers": {
    "chrome": {
      "command": "bunx",
      "args": ["-y", "@cypherpotato/chrome-mcp", "--mcp"]
    }
  }
}

bun link 후 로컬 체크아웃의 경우, bunx를 사용하는 대신 MCP 구성이 링크된 실행 파일을 직접 가리키도록 하세요:

{
  "command": "C:\\Users\\<user>\\.bun\\bin\\chrome-mcp-electron",
  "args": ["--mcp"]
}

CLI

chrome-mcp-electron --mcp
chrome-mcp-electron --daemon
chrome-mcp-electron --status
chrome-mcp-electron --stop-daemon
chrome-mcp-electron --help

--mcp는 필요할 때 데몬을 백그라운드에서 시작한 다음 stdio를 통해 MCP를 제공합니다. MCP 프로세스를 닫아도 데몬이 중지되거나 Chrome 확장 프로그램 연결이 끊기지 않습니다.

도구

공개 도구 이름과 입력 스키마는 Browser MCP와 일치합니다:

• browser_toggle_session

• browser_import_session

• browser_run_actions

• browser_get_context

browser_toggle_session({ "action": "start" })는 기본 Chrome 인스턴스에서 탭을 엽니다. 여러 인스턴스가 연결된 경우 확장 프로그램 팝업에서 기본값을 선택하세요. 확장 프로그램이 보고한 기존 탭도 session_id 값을 받으며 직접 제어할 수 있습니다.

browser_get_context는 연결된 모든 인스턴스와 해당 탭을 나열합니다. URL은 쿼리 문자열 없이 반환됩니다.

여러 Chrome 인스턴스 및 프로필

압축 해제된 확장 프로그램을 각 프로필에 별도로 설치하세요. 각 설치는 해당 프로필에 저장된 안정적인 무작위 인스턴스 ID를 생성하고 데몬에 자동으로 다시 연결됩니다. 인스턴스 이름은 고유할 필요는 없지만, 서로 다른 이름을 사용하는 것이 좋습니다.

데몬은 확장 프로그램 또는 서비스 워커가 재시작된 후 탭을 조정합니다. 세션은 해당 세션을 소유한 확장 프로그램이 연결되어 있고 탭이 아직 존재하는 동안 주소를 지정할 수 있습니다.

기능

browser_run_actions는 Browser MCP와 동일한 브라우저 헬퍼 표면을 지원합니다:

• 스냅샷 및 JavaScript 평가;

• 클릭, 오른쪽 클릭, 호버, 드래그, 스크롤 및 타이핑;

• 탐색;

• 스크린샷;

• 콘솔 및 네트워크 로그;

• Chrome이 아직 보유하고 있는 네트워크 요청 세부 정보 및 응답 본문;

• 반응형 뷰포트 에뮬레이션 및 색상 구성표 에뮬레이션;

• JavaScript alert, confirm, prompt 처리.

제한 사항

• Chrome은 탭당 하나의 디버거 연결만 허용합니다. 해당 탭을 제어하기 전에 DevTools를 닫으세요. DevTools를 열면 확장 프로그램이 분리될 수 있습니다.

• Chrome 내부 페이지, 확장 프로그램 페이지, Chrome Web Store 및 기타 제한된 스킴은 제어하거나 에이전트 세션으로 노출할 수 없습니다.

• 확장 프로그램은 각 프로필에 설치되어야 합니다. 한 프로필은 다른 프로필의 탭을 검사할 수 없습니다.

• 디버거 권한은 탭이 연결되어 있는 동안 Chrome 경고를 표시합니다.

• 응답 본문은 Chrome의 네트워크 버퍼에서 만료될 수 있습니다.

• 네이티브 터치 입력과 브라우저 내부 다운로드 CDP API는 chrome.debugger를 통해 노출되지 않습니다.

개발

bun run check
bun run test

테스트 스위트는 Chrome을 열지 않고도 상주 데몬의 수명 주기, 인증, 탭/세션 조정, 여러 인스턴스, 기본 인스턴스 선택, 작업 라우팅 및 재연결 동작을 검증하기 위해 mock 확장 프로그램 WebSocket 클라이언트를 사용합니다.

내부 프로토콜은 docs/protocol.md에 문서화되어 있습니다.