Browser MCP

Chrome/Edge 브라우저를 모든 AI 에이전트를 위한 MCP 도구로 노출하세요. Chrome 확장 프로그램(Manifest V3)이 MCP 서버 자체 역할을 합니다. code-mcp-gateway에 연결하여 MCP 요청을 그 자리에서 응답합니다 — 로컬 서버가 필요 없습니다. code-mcp와 동일한 JSON-RPC 프로토콜을 사용하므로 기존 에이전트 설정에 바로 통합됩니다.

작동 방식

flowchart LR
  subgraph Agent["Agent side"]
    A["MCP client / AI agent"]
  end

  subgraph Gateway["code-mcp-gateway (Cloudflare Worker)"]
    G["wss://code-mcp.tuanm.dev/ws/<id>"]
  end

  subgraph Browser["Your browser"]
    E["Extension (MV3)<br/>service worker = MCP server<br/>offscreen = WS bridge"]
    P["Page (content script)"]
  end

  A -- "MCP JSON-RPC" --> G
  G -- "register / keepalive /<br/>forward requests" --> E
  E -- "CDP / tabs / scripting" --> P

팝업에서 Device ID와 Token을 입력받습니다. 확장 프로그램은 게이트웨이에 직접 연결하여(등록, 25초마다 keepalive, 75초 watchdog, 지터 백오프 재연결) initialize / tools/list / tools/call을 그 자리에서 제공합니다. 게이트웨이에 도달할 수 있는 모든 에이전트가 브라우저를 제어할 수 있습니다.

선택적 로컬 서버(browser-mcp.ts)는 파일 저장소(file_read, 대용량 다운로드/업로드)와 일반 로컬 MCP HTTP 엔드포인트를 추가합니다. 로컬 서버를 참조하세요.

빠른 시작

Chrome 또는 Edge >= 111. Bun >= 1.1은 로컬 서버 또는 개발 도구에만 필요합니다 — 확장 프로그램은 단독으로 동작합니다.

1. 확장 프로그램을 로드합니다. chrome://extensions를 열고 개발자 모드를 활성화한 다음, 압축 해제된 확장 프로그램 로드를 클릭하고 packages/browser-extension을 선택합니다. (또는 bun browser-mcp.ts를 실행하고 http://127.0.0.1:7777/extension에서 zip을 다운로드합니다.)

2. 연결합니다. 툴바 아이콘을 클릭합니다(연결되면 MCP 마크가 녹색으로 변합니다). 게이트웨이 Device ID와 Token을 입력하고 연결을 클릭합니다. 팝업에 **연결됨 (게이트웨이)**가 표시됩니다.

3. 사용합니다. 모든 MCP 클라이언트를 게이트웨이 디바이스에 연결하세요. 확장 프로그램은 tools/list에 47개의 도구로 응답합니다.

토큰은 게이트웨이에서 이 디바이스에 대해 구성된 토큰과 일치해야 합니다. 게이트웨이는 각 요청과 함께 토큰을 전달하고 확장 프로그램이 이를 검증합니다. 비워 두면 게이트웨이에 도달하는 누구나 브라우저를 제어할 수 있습니다.

로컬 서버

파일 저장소(file_read, 512KB 초과 다운로드/업로드) 또는 로컬 MCP HTTP 엔드포인트에만 필요합니다:

bun browser-mcp.ts                  # http://127.0.0.1:7777/mcp
bun browser-mcp.ts --token <s>      # require auth on /mcp + /files

서버가 실행 중이면 팝업은 ID + Token을 서버 자체의 게이트웨이 링크에도 전달합니다. 서버가 없어도 확장 프로그램은 여전히 직접 동작합니다. 로컬 클라이언트는 http://127.0.0.1:7777/mcp를 사용합니다 — mcp-client.example.json을 참조하세요(--token으로 실행하는 경우 "headers": { "Authorization": "Bearer <token>" }를 추가). 확인: curl -s http://127.0.0.1:7777/health.

code-mcp-gateway를 통한 원격 액세스

• 직접 (기본). 팝업에 ID + Token을 입력합니다. 확장 프로그램이 MCP 자체를 제공합니다. 로컬 서버가 없습니다.

• 서버 측 링크. 로컬 서버가 있으면 팝업이 wss://code-mcp.tuanm.dev/ws/<id>에 연결하고 서버가 HTTP를 통해 MCP에 응답합니다.

• CLI (사용자 지정 게이트웨이):

bun browser-mcp.ts --gateway <domain> --token <s> --id <device-id>

직접 모드와 동일한 프로토콜입니다. 게이트웨이 디바이스에서 동일한 --token을 사용하세요. 토큰 없이 게이트웨이 모드를 실행하지 마세요. BMCP_GATEWAY_DOMAIN을 설정하여 팝업의 기본 게이트웨이 호스트를 재정의하세요.

도구 (47)

@ref 시스템을 사용한 요소 검색: snapshot은 [ref=eN] 마커가 있는 대화형 요소 트리를 반환합니다. 모든 상호작용 도구는 ref 또는 CSS 선택자를 허용합니다(ref는 캐시되어 자동으로 해석됩니다. 오래된 ref는 "run snapshot again" 오류를 발생시킵니다).

• 검색 — snapshot, find (role/name/text/label/placeholder/title/testid/selector), get, is

• 상호작용 — click, dblclick, type, fill, check, uncheck, select, hover, focus, press, drag, scroll, upload

• 탐색 — navigate, reload, back, forward, close, tabs, window

• 페이지 읽기 — extract, execute, screenshot (image block), pdf, wait, highlight

• 상태 및 디버깅 — store, cookies, storage, console, errors, network, status, file_read

• 에뮬레이션 및 제어 — emulate, set (viewport/device/geo/offline/headers/media), perms, auth, dialog, frames, touch, download

콘솔/오류/네트워크 캡처는 첫 번째 호출에서 시작됩니다(지연). 따라서 트래픽을 캡처하려면 활성화한 후 새로고침하거나 탐색하세요. 뒤로/앞으로는 CDP 탐색 기록을 사용합니다. 전체 스키마는 curl -s -X POST http://127.0.0.1:7777/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'를 실행하세요.

플래그

보안

• Origin 게이트. /browser/ws는 chrome-extension:// Origin만 허용합니다. /mcp 및 /files/*는 localhost가 아닌 브라우저 Origin을 거부합니다 — 악성 웹사이트가 localhost를 통해 브라우저를 제어할 수 없습니다(CSRF). 네이티브 MCP 클라이언트(Origin 헤더 없음)는 영향을 받지 않습니다.

• **--token**은 /mcp 및 /files/*을 보호합니다(?token= 또는 Bearer). --extension-token은 확장 프로그램이 브리지에서 제시해야 하는 비밀을 추가합니다.

• 파일 ID는 엄격한 패턴으로 검증되는 12자리 임의 16진수입니다. 업로드 파일 이름은 안전하게 처리됩니다. 크기 제한: 업로드 500 MiB, 스크린샷 8 MiB 인라인.

• **chrome.debugger**는 연결되는 동안 노란색 인포바를 표시합니다(동의 신호). perms/cookies는 가능한 경우 비디버거 API를 사용합니다.

• 기본적으로 127.0.0.1에 바인딩됩니다. --token 없이 0.0.0.0에 바인딩하면 경고가 출력됩니다.

타임아웃

브리지 명령: 기본 30초, navigate/execute/wait_for는 60초, download/file_upload는 120초 — 로컬에서는 120초, 게이트웨이 모드에서는 55초로 제한됩니다(게이트웨이는 60초 후 전달을 중단합니다). 도구는 bridge_timeout을 받아 재정의할 수 있습니다.

개발

bun run check   # syntax-check server + scripts + extension JS
bun run test    # mock-extension + mock-gateway E2E suite
bun run build   # rebuild dist/browser-extension.zip
bun browser-mcp.ts  # run the server