Browser Navigator MCP

AI 어시스턴트가 CDP(Chrome DevTools Protocol)를 통해 Brave 브라우저를 완전히 제어할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. OSINT 조사, 소셜 미디어 크롤링, 일반적인 웹 자동화를 위해 만들어졌습니다.

기존에 실행 중인 Brave 인스턴스에 연결하거나(또는 새로 실행) 탭을 건드리지 않습니다. 복제본이 아닌 브라우저 자체에 연결됩니다.

기능

• 🧭 전체 브라우저 제어 — 탐색, 클릭, 입력, 스크롤, 호버, 스크린샷, PDF 내보내기

• 🪟 창 및 탭 관리 — 창/탭 나열, 열기, 전환, 닫기

• 🔐 CAPTCHA 탐지 — reCAPTCHA, hCaptcha, Cloudflare Turnstile 및 challenge를 자동으로 감지한 후, 사람이 해결할 때까지 대기

• 🍪 세션 유지 — 쿠키 저장/로드로 실행 사이에 로그인 상태 유지

• 🎥 비디오 제어 — 모든 HTML5 플레이어(Youtube 등)에서 재생/일시정지/탐색/음량

• 🔍 소셜 검색 — Google, X/Twitter, Instagram, Facebook, LinkedIn, TikTok, YouTube에서 원툴 검색

• 🔧 임의의 JS 실행 — 그 외의 작업은 execute_js 사용(명시적 확인 플래그 필요)

• 🏥 헬스 체크 — 서버 및 브라우저 연결 상태 확인

요구 사항

• Node.js 20+

• Brave 브라우저(표준 경로에 설치되거나, BRAVE_PATH로 지정)

• Playwright 브라우저 다운로드는 불필요함 — 서버는 CDP를 통해 Brave를 직접 구동합니다.

설치

git clone <your-repo-url>
cd brave-browser-mcp
npm install

빠른 시작

1. 디버그 포트로 Brave 실행

./launch-brave.sh

이 명령은 --remote-debugging-port=9222로 Brave를 시작합니다. 기존 Brave 인스턴스를 절대 종료하지 않습니다 — 포트 9222가 이미 사용 중이면 그대로 둡니다.

또는 brave --remote-debugging-port=9222로 수동 시작할 수도 있습니다. Brave가 디버그 포트 없이 이미 실행 중이라면, MCP는 브라우저를 닫고 다시 시도하라고 요청할 것입니다. 실행 중인 브라우저를 자동으로 종료하지는 않습니다.

2. 서버 실행

node index.js

서버는 stdio를 통해 MCP와 통신합니다. connect_brave가 실행 중인 Brave 인스턴스에 자동으로 연결합니다.

3. MCP 서버로 등록

opencode의 경우 opencode.json에 추가:

{
  "mcp": {
    "browser-navigator": {
      "type": "local",
      "command": ["node", "index.js"],
      "cwd": "/absolute/path/to/brave-browser-mcp",
      "enabled": true
    }
  }
}

Claude Desktop의 경우 claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "browser-navigator": {
      "command": "node",
      "args": ["/absolute/path/to/brave-browser-mcp/index.js"]
    }
  }
}

도구

CAPTCHA 처리

CAPTCHA는 navigate/navigate_history 후 자동으로 감지되며 get_page_info에서 보고됩니다. 해결되지 않은 CAPTCHA가 발견되면 자동화는 일시 중지되고 사용자에게 해결을 요청합니다 — 이 도구는 CAPTCHA를 우회할 수 없습니다(그렇게 하지도 않습니다).

지원되는 유형: reCAPTCHA, hCaptcha, Cloudflare Turnstile, Cloudflare Challenge.

보안 참고 사항

• execute_js는 confirm=true가 필요하며, 5000자 및 출력 5000자로 제한됩니다.

• 스크린샷 및 쿠키 경로는 경로 탐색(path traversal)에 대해 검증됩니다.

• 쿠키는 0o600 권한으로, 디렉터리는 0o700 권한으로 저장됩니다.

• 서버는 자체적으로 실행한 브라우저만 종료하며, 이미 실행 중인 브라우저는 절대 종료하지 않습니다.

• 전체 보안 및 코드 품질 감사는 AUDIT.md를 참조하세요.

테스트

테스트 스위트는 MCP stdio 프로토콜을 통해 실행됩니다 (Brave가 9222 포트에서 실행 중이어야 함):

node test.cjs

탐색, CAPTCHA, 탭, 스크린샷, 쿠키, 비디오, 보안 강화를 포함한 53개의 assertion을 다룹니다.

라이선스

비상업적 라이선스 1.0.0 — 전체 조건은 LICENSE 참조.

비상업적 용도(연구, 교육, 취미)로는 무료로 사용할 수 있습니다. 상업적 사용을 위해서는 먼저 작성자에게 문의하세요. — 이메일: your-email@example.com

감사

공식 감사 보고서는 AUDIT.md에 있으며, 알려진 제한 사항과 향후 개선 사항도 있습니다.

기능 요청, 버그, 개선 아이디어는 GitHub Issues로 제출해 주세요.