browser-tools-mcp

OpenCode/Claude Code를 위한 지속적인 헤드형 Chromium 브라우저 제어 도구로, Claude Code의 브라우저 도구 스타일을 따릅니다. OpenCode에는 기본 브라우저 도구가 없고 custom-scraper(일반 HTTP)는 JavaScript가 많이 사용된 페이지나 로그인이 필요한 페이지를 읽을 수 없기 때문에 2026-08-05에 제작되었습니다.

아키텍처

MCP 서버 프로세스는 단일 브라우저 관리자입니다. OpenCode는 전체 CLI 세션 동안 stdio 서버를 유지하므로 브라우저는 에이전트 턴이 바뀌어도 유지됩니다. 브라우저가 충돌하거나 창이 닫히면 다음 도구 호출 시 자동으로 다시 시작됩니다(server/browser.js).

실행 구성: headless: false, slowMo: 100, 뷰포트 1280x800, 데스크톱 Chrome UA, --disable-blink-features=AutomationControlled.

Related MCP server: Controlium

파일

• server/server.js — MCP 진입점, 5개 도구 + 스키마를 등록합니다.

• server/browser.js — 단일 브라우저/컨텍스트/페이지 관리자 및 재시작 로직.

• server/tools.js — 작업(상호작용 트리, 대상 지정, 강조, 스크린샷).

• server/_self_verify.js — 독립형 시나리오 테스트: npm run verify.

• shots/ — browser_inspect의 스크린샷.

• USAGE.md — 에이전트용 규칙(OpenCode instructions에 연결됨).

도구

요소 대상 지정은 Claude Code 규칙을 따릅니다. browser_inspect는 각 상호작용 가능한 요소에 숫자 target을 할당하고 DOM에 data-bt-target으로 태그를 지정하여 이후 작업이 정확히 동일한 요소를 해석하도록 합니다(표시된 필터링된 인덱스는 숨겨진 입력이 있는 페이지에서 필터링되지 않은 .nth()와 어긋날 수 있습니다). 요소는 클릭하기 전에 잠시 강조 표시되어 사용자가 작업을 볼 수 있습니다.

검증

npm run verify        # navigate -> inspect -> click -> fill -> crash-recovery

2026-08-05 검증 완료: example.com 탐색/검사/클릭, 대상별 Google 채우기, 종료 후 재시작이 모두 통과했습니다. 5개 도구 모두 등록되어 실제 MCP stdio 프로토콜을 통해 응답했습니다.

운영 참고 사항

• 헤드형은 데스크톱을 의미합니다. Chromium 창을 시작하려면 대화형 세션이 필요합니다. 헤드리스/연결되지 않은 머신에서는 시작이 실패하므로, 모르는 척하지 말고 그렇게 보고하세요.

• 격리된 브라우저. 이것은 Luigi의 로그인된 Chrome이 아닙니다(그것은 chrome-bridge입니다). 로그인된 세션, 확장 프로그램이 없으며 전체 쓰기 권한이 있습니다.

• 사람 게이트. 명시적인 지시 없이는 로그인/주문/전송을 수행하지 마세요. browser_request_human은 사람이 응답할 때까지 중지(중단)를 의미합니다.

• ~/.config/opencode/opencode.jsonc에 browser-tools MCP 서버로 등록되어 있으며, 사용 규칙은 USAGE.md를 통해 instructions에 연결됩니다.