Browser Bridge

AI ↔ 브라우저 제어 브리지: 브라우저를 MCP 도구 모음으로 바꿉니다. 모든 MCP 클라이언트(AI 프로그램)는 표준 MCP 프로토콜을 통해 browser_snapshot / browser_click / browser_type 등의 도구를 호출하여 실제 브라우저에서 웹페이지를 조작할 수 있습니다.

• 모든 MCP 클라이언트 지원: Claude, codex, 사용자 정의 agent, curl

• 기본 팔로우 모드: AI가 현재 활성화된 탭을 자동으로 제어하며, 별도 설정이 필요 없습니다.

• 실제 브라우저, headless 아님: 로그인 상태, 캡차(수동 입력 안내), 반크롤링 특성이 자연스럽습니다.

빠른 시작

1. 다운로드

Releases에서 하나의 압축 파일을 다운로드합니다:

• browser-bridge-<platform>-<arch>.zip — 사용자 머신의 플랫폼에 맞게 선택

아무 디렉터리에 압축을 풉니다(이하 <DIR>로 표기). 디렉터리에는 browser-bridge/(확장 프로그램), browser-bridge-host, install-host.sh(Windows의 경우 install-host.ps1)가 포함되어 있습니다.

2. 확장 프로그램 로드

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

2. 오른쪽 위에서 개발자 모드를 켭니다.

3. '압축 해제된 확장 프로그램 로드'를 클릭하고 압축을 푼 browser-bridge/ 디렉터리를 선택합니다.

3. host 설치

macOS / Linux:

cd <DIR>
./install-host.sh         # Windows(PowerShell): .\install-host.ps1

실행하면 감지된 브라우저가 나열되며, Enter를 누르면 모두 설치하고, 번호를 입력하면 특정 브라우저를 선택합니다. 인자로 직접 지정할 수도 있습니다:

./install-host.sh --all      # 安装到全部浏览器
./install-host.sh --chrome   # 只装 Chrome(--chromium / --edge 同理)

확장 프로그램 ID는 내장되어 고정되어 있어 수동으로 입력할 필요가 없습니다. 확장 ID가 다르면 인자를 추가로 전달할 수 있습니다: ./install-host.sh <당신의 확장 ID>.

브라우저가 이미 열려 있다면 설치 후 완전히 종료하고 브라우저를 다시 시작하세요.

4. 사용

아무 MCP 클라이언트나 연결합니다:

MCP server: http://127.0.0.1:1234/mcp

포트가 사용 중이면 자동으로 +1됩니다. 실제 포트는 확장 프로그램 팝업(연결됨 · MCP 포트 xxxx) 또는 ~/.browser-bridge/port에서 확인하세요.

codex 구성 예시(~/.codex/config.toml):

[mcp_servers.browser]
url = "http://127.0.0.1:1234/mcp"

그런 다음 AI에게 "이 페이지 좀 봐줘…"라고 말하면 됩니다.

Related MCP server: BrowserPilot

MCP 도구

AI가 스스로 오케스트레이션: snapshot → 결정 → 조작 → 다시 snapshot, 작업이 완료될 때까지 반복합니다.

제어 모드

• 팔로우 모드(기본): 현재 활성화된 탭을 제어하며, 탭을 전환하면 대상도 전환됩니다.

• 고정 모드: 특정 탭을 잠급니다(전환해도 따라가지 않음). popup에서 한 번에 고정/해제하거나 AI가 browser_use_tab을 호출합니다.

도구 모음 아이콘 배지: 없음 = 팔로우 중; AI 호박색 = 고정됨; ! 빨간색 = 연결 오류.

아키텍처

任意 MCP 客户端
   │ MCP (Streamable HTTP, 127.0.0.1:1234/mcp)
browser-bridge host(单进程 = MCP ↔ 帧协议翻译器)
   │ native messaging(stdin/stdout 帧)
Chrome 扩展
   ├─ background:转发、目标解析、保活、状态徽标
   └─ content script:快照 / 执行

MV3 확장 프로그램은 포트를 수신할 수 없으므로 native host가 유일한 통로입니다(Chrome 공식 DevTools MCP와 동일 구조).

소스에서 빌드(개발자)

bun 필요:

bun install
bun run build                    # 当前平台 host + 扩展
./scripts/install-host.sh        # 注册 host(默认内置扩展 ID)
bun run scripts/build.ts --all   # 交叉编译全部平台 + 发布包(发布用)
bun test                         # 单元 + MCP API 集成测试(无需浏览器)

구성

• BROWSER_BRIDGE_PORT: MCP 초기 포트(기본 1234, 사용 중이면 자동 +1)

• BROWSER_BRIDGE_MOCK=1: 확장 프로그램 응답 모의(개발 테스트용)

문제 해결

License

MIT