Browser MCP Bridge

Claude Code가 브라우저에 직접 액세스할 수 있도록 합니다. 자연어를 통해 페이지를 검사하고, 콘솔 오류를 읽고, 네트워크 요청을 모니터링하고, 스크린샷을 캡처하고, JavaScript를 실행하세요.

기능 소개

Browser MCP Bridge는 Model Context Protocol (MCP)를 통해 Chrome 브라우저를 Claude Code에 연결합니다. 이 브릿지는 두 부분으로 구성됩니다:

1. Chrome 확장 프로그램: 브라우저 데이터(페이지 콘텐츠, DOM, 콘솔, 네트워크, 성능, 접근성)를 캡처합니다.

2. MCP 서버: 11개의 특수 도구를 통해 해당 데이터를 Claude Code에 노출합니다.

연결이 완료되면 Claude Code에게 다음과 같이 요청할 수 있습니다:

• "이 페이지의 접근성 문제를 확인해 줘"

• "이 페이지의 콘솔 오류가 무엇인가요?"

• "실패한 API 요청을 보여줘"

• "이 페이지의 성능을 분석해 줘"

• "현재 페이지에서 document.querySelectorAll('a')를 실행해 줘"

Related MCP server: Browser Agent MCP

빠른 시작

5분 이내에 시작할 수 있습니다:

1. 서버 설치

git clone https://github.com/anthropics/browser-mcp-bridge.git
cd browser-mcp-bridge
npm run install-server

2. 브라우저 확장 프로그램 설치

1. chrome://extensions/ (또는 edge://extensions/)를 엽니다.

2. 개발자 모드를 활성화합니다 (우측 상단 토글).

3. 압축해제된 확장 프로그램을 로드합니다를 클릭합니다.

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

툴바에 "Browser MCP Bridge" 아이콘이 표시되어야 합니다.

3. Claude Code 구성

claude mcp add --scope user --transport http browser-mcp http://127.0.0.1:6009/mcp

4. 서버 시작 및 연결

npm start

그런 다음 Browser MCP Bridge 확장 프로그램 아이콘을 클릭하고 Connect를 클릭합니다. 상태 표시등이 녹색으로 바뀌어야 합니다.

이제 Claude Code가 브라우저에 액세스할 수 있습니다.

프로젝트 구조

browser-mcp-bridge/
├── extension/ # Chrome extension
│ ├── manifest.json # Manifest V3 configuration
│ ├── background.js # Service worker (WebSocket, tab management)
│ ├── content.js # Content script (page data extraction)
│ ├── inject.js # Injected script (console/network interception)
│ ├── popup.html/js # Extension popup (connection management)
│ ├── devtools.html/js # DevTools integration entry point
│ ├── panel.html/js # Custom DevTools panel UI
│ └── icons/ # Extension icons
├── server/ # Node.js MCP server
│ ├── server.js # HTTP MCP server + WebSocket server
│ └── package.json # Server dependencies
├── rust-server/ # Rust MCP server (experimental)
│ ├── src/ # Rust source code
│ ├── Cargo.toml # Rust dependencies
│ └── config.toml # Server configuration
├── browser-mcp-rust-server.service # systemd user service unit
├── install-rust-service.sh # Service install/uninstall script
├── start-rust-server.sh # PM2 launch script for Rust server
├── ecosystem.config.cjs # PM2 process manager config
├── ARCHITECTURE.md # System architecture documentation
├── API_REFERENCE.md # Complete MCP tools reference
├── DATA_OPTIMIZATION.md # Data filtering and pagination guide
└── package.json # Root scripts and orchestration

작동 원리

┌─────────────────┐ WebSocket ┌──────────────────┐ HTTP/MCP ┌─────────────────┐
│ Chrome Extension │ ◄──────────────── │ MCP Server │ ◄──────────────── │ Claude Code │
│ │ ws://localhost │ (port 6009) │ http://localhost │ (one or more │
│ • content.js │ :6009/ws │ │ :6009/mcp │ instances) │
│ • background.js │ ─────────────────►│ • 11 MCP tools │ ─────────────────►│ │
│ • inject.js │ │ • Resources │ │ │
│ • DevTools │ │ • Data filtering│ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘

1. 확장 프로그램은 콘텐츠 스크립트와 Chrome API를 통해 브라우저 데이터를 캡처합니다.

2. WebSocket 연결을 통해 6009 포트의 MCP 서버로 데이터를 전송합니다.

3. Claude Code는 /mcp의 HTTP 전송을 통해 서버에 연결합니다.

4. 여러 Claude Code 인스턴스가 동일한 서버를 공유할 수 있습니다.

사용 가능한 도구

모든 도구는 특정 탭을 대상으로 하는 선택적 tabId 매개변수를 지원합니다. 전체 매개변수 문서는 API_REFERENCE.md를 참조하세요.

예시 워크플로우

콘솔 오류 디버깅

Claude Code에게 요청하세요: "브라우저 콘솔에 어떤 오류가 표시되나요?"

Claude Code는 get_console_messages를 사용하여 오류와 경고를 검색한 다음, 이를 분석하고 수정 사항을 제안합니다.

실패한 API 호출 분석

요청하세요: "실패한 네트워크 요청을 보여주고 디버깅을 도와줘"

Claude Code는 실패 필터링이 적용된 get_network_requests를 사용하여 4xx/5xx 응답을 찾은 다음, 요청/응답 본문을 검사하여 단서를 찾습니다.

접근성 감사

요청하세요: "이 페이지의 접근성 문제를 확인해 줘"

Claude Code는 get_accessibility_tree와 get_page_content를 호출하여 ARIA 속성, 헤딩 구조, 대체 텍스트 및 시맨틱 HTML을 분석합니다.

성능 분석

요청하세요: "이 페이지의 성능은 어떤가요? 문제가 있나요?"

get_performance_metrics와 get_network_requests를 사용하여 느린 리소스, 큰 페이로드 및 Core Web Vitals 문제를 식별합니다.

시각적 검사

요청하세요: "현재 페이지의 스크린샷을 찍어줘"

capture_screenshot은 표시된 탭의 PNG 또는 JPEG 스냅샷을 반환합니다.

구성

서버 포트

서버는 기본적으로 6009 포트를 사용합니다. 다른 포트를 사용하려면:

MCP_SERVER_PORT=8080 npm start

포트를 변경하는 경우, 팝업에서 확장 프로그램의 WebSocket URL(ws://localhost:8080/ws)과 Claude Code MCP 구성을 업데이트하세요.

확장 프로그램 설정

확장 프로그램 아이콘을 클릭하여 다음을 수행하세요:

• 연결 상태 확인

• WebSocket 서버 URL 변경

• 수동으로 데이터 캡처 트리거

• 메시지 통계 보기

PM2로 실행 (프로덕션)

# Start with PM2
npm run pm2:start

# Other PM2 commands
npm run pm2:status # Check status
npm run pm2:logs # View logs
npm run pm2:restart # Restart
npm run pm2:stop # Stop

부팅 시 자동 시작 및 고급 구성은 PM2_GUIDE.md를 참조하세요.

systemd로 Rust 서버 실행 (Linux)

Rust 서버는 자동 시작 및 프로세스 감독을 위해 systemd 사용자 서비스로 관리할 수 있습니다.

빠른 설정:

# Build and install the service in one step
./install-rust-service.sh

# Or install without rebuilding (if you already have a release binary)
./install-rust-service.sh --no-build

서비스 관리:

systemctl --user status browser-mcp-rust-server # Check status
journalctl --user -u browser-mcp-rust-server -f # Follow logs
systemctl --user restart browser-mcp-rust-server # Restart
systemctl --user stop browser-mcp-rust-server # Stop

서비스는 로그인 시 자동 시작됩니다. 로그인 세션 없이도 시작하려면 (헤드리스/SSH 액세스에 유용):

loginctl enable-linger $USER

제거:

./install-rust-service.sh --uninstall

수동 설치 (스크립트를 사용하지 않으려는 경우):

# Build the release binary
cd rust-server && cargo build --release

# Copy the service file
mkdir -p ~/.config/systemd/user
cp browser-mcp-rust-server.service ~/.config/systemd/user/

# If your repo is NOT at ~/dev/browser-mcp-bridge, edit the paths:
# systemctl --user edit browser-mcp-rust-server
# and override ExecStart and WorkingDirectory

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now browser-mcp-rust-server

구성:

서비스는 기본적으로 rust-server/config.toml을 읽습니다. 포트나 기타 설정을 변경하려면 config.toml을 편집하고 다시 시작하세요:

systemctl --user restart browser-mcp-rust-server

로그 상세 수준을 위해 RUST_LOG를 설정하세요. 기본값은 info입니다. 드롭인 파일로 재정의하세요:

systemctl --user edit browser-mcp-rust-server

[Service]
Environment=RUST_LOG=debug

다른 클라이언트를 위한 MCP 구성

JSON 구성을 사용하는 MCP 클라이언트의 경우:

{
 "mcpServers": {
 "browser-mcp": {
 "url": "http://localhost:6009/mcp"
 }
 }
}

개발

서버 개발

npm run dev # Start with --watch (auto-restart on changes)
DEBUG=* npm start # Verbose logging

확장 프로그램 개발

1. extension/ 내의 파일들을 수정합니다.

2. chrome://extensions/로 이동합니다.

3. Browser MCP Bridge 확장 프로그램의 새로고침 버튼을 클릭합니다.

상태 확인

npm run health-check
# or: curl http://localhost:6009/health

새로운 도구 추가

1. server.js → ListToolsRequestSchema 핸들러에 도구 정의를 추가합니다.

2. server.js → CallToolRequestSchema 핸들러에 도구 로직을 구현합니다.

3. extension/background.js에 브라우저 측 핸들러를 추가합니다.

4. Claude Code로 테스트합니다.

데이터 최적화

서버는 AI 에이전트가 응답을 관리하기 쉽도록 지능형 기본값을 구현합니다:

• HTML: 50KB에서 잘림 (텍스트는 30KB)

• DOM: 500개 노드로 제한, 스크립트/스타일 제외

• 콘솔: 기본적으로 오류 및 경고 반환

• 네트워크: 50개 요청, 실패한 요청 우선 정렬, 본문 제외

모든 제한은 요청별로 구성 가능합니다. 전체 필터링, 페이지 매김 및 최적화 가이드는 DATA_OPTIMIZATION.md를 참조하세요.

문제 해결

확장 프로그램이 연결되지 않음

1. 서버가 실행 중인지 확인: curl http://localhost:6009/health

2. 확장 프로그램 팝업의 WebSocket URL이 서버 포트와 일치하는지 확인

3. 브라우저 콘솔에서 오류 확인 (chrome://extensions/ → 오류 링크)

Claude Code가 도구를 찾을 수 없음

1. MCP 구성 확인: claude mcp list

2. 서버가 실행 중이고 정상인지 확인

3. 서버 다시 추가: claude mcp remove browser-mcp && claude mcp add --scope user --transport http browser-mcp http://127.0.0.1:6009/mcp

도구에서 데이터가 반환되지 않음

1. 확장 프로그램이 연결되었는지 확인 (팝업에서 녹색 상태)

2. 브라우저에서 페이지로 이동 — 확장 프로그램은 활성 페이지가 필요합니다.

3. 탭 ID가 올바른지 확인 (get_browser_tabs를 먼저 사용)

서버가 시작되지 않음

1. Node.js 버전 확인: node --version (18.0.0 이상 필요)

2. 종속성 설치: npm run install-server

3. 6009 포트 사용 여부 확인: lsof -i :6009

추가 읽기

• ARCHITECTURE.md — 시스템 설계, 데이터 흐름 및 구성 요소 세부 정보

• API_REFERENCE.md — 모든 매개변수가 포함된 전체 MCP 도구 참조

• DATA_OPTIMIZATION.md — 필터링, 페이지 매김 및 성능 튜닝

요구 사항

• Node.js 18.0.0+

• Chrome, Edge 또는 Chromium 기반 브라우저

• Claude Code CLI (또는 MCP 호환 클라이언트)

라이선스

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers