BrowserTools Installation Guide (BrowserTools 설치 가이드)

날짜:

BrowserTools 설치 가이드

BrowserTools는 AI 코드 에디터와 에이전트를 웹 브라우저에 직접 통합하여 디버깅 및 개발 경험을 향상하는 도구이다.

요구 사항

  • NodeJS 설치
  • Google Chrome 또는 Chromium 기반 브라우저
  • MCP 클라이언트 애플리케이션 (Cursor, Windsurf, RooCode, Cline, Continue, Zed, Claude Desktop)

참고: MCP(Model Context Protocol)는 Anthropic 모델에 특화되어 있다. Cursor와 같은 에디터 사용 시, Claude 3.5 Sonnet 모델을 선택하여 컴포저 에이전트를 활성화해야 한다.

설치

  1. 크롬 확장 프로그램 다운로드
    공식 Google 확장 프로그램 마켓플레이스 승인 대기 중이다. 현재는 여기서 확장 프로그램 다운로드하거나 다음 Git 리포지토리를 클론하여 chrome-extension 디렉토리 내에서 확장 프로그램을 찾는다.

    git clone https://github.com/AgentDeskAI/browser-tools-mcp.git

  2. 크롬 확장 프로그램 설치

    • '확장 프로그램 관리' 창을 연다.
      확장 프로그램 관리 열기
    • '개발자 모드'를 활성화하고 '압축 해제된 확장 프로그램 로드'를 클릭한다.
      개발자 모드 활성화
    • 이전에 다운로드한 크롬 확장 프로그램 폴더로 이동하여 압축이 해제되었는지 확인하고 '선택'을 클릭한다. 이제 확장 프로그램 목록에서 BrowserToolsMCP를 볼 수 있다.
      압축 해제된 확장 프로그램 로드

  3. BrowserTools MCP 도구 설정
    사용하는 MCP 클라이언트에서 BrowserTools MCP 서버를 설정한다. Cursor를 예시로 설명한다.

    • 'Cursor 설정'으로 이동한다.
      Cursor 설정 열기
    • 'Features'로 이동하여 'MCP Servers'까지 스크롤한 후 'Add new MCP server'를 클릭한다.
      Cursor 기능 설정
    • 고유한 이름(예: browser-tools)을 지정하고, 타입을 'command'로 설정하고, 다음 명령어를 입력한다.
      • MacOS:
        shell npx @agentdeskai/browser-tools-mcp@1.2.0
      • Windows NPX:
        shell cmd /c npx -y @agentdeskai/browser-tools-mcp@1.2.0
      • NPX 경로를 찾으려면 다음 명령어를 사용한다 (Windows):
        shell which npx
        MCP 도구 추가
    • MCP 서버가 연결되었는지 확인한다. 모든 도구가 목록에 표시되고 도구 이름 옆에 녹색 원이 보여야 한다.
      MCP 도구 확인
      몇 초 기다리거나 등록되지 않으면 새로 고침 버튼을 여러 번 클릭한다. 그래도 등록되지 않으면 올바른 명령어를 입력했는지 확인한다.

  4. BrowserTools 서버 실행
    크롬 확장 프로그램에서 로그를 집계하고 스크린샷 캡처를 위한 웹소켓을 설정한다. 터미널에서 다음 명령어를 실행한다.

    npx @agentdeskai/browser-tools-server@1.2.0

    참고: browser-tools-server는 포트 3025에서 실행된다. 이 포트에서 실행 중인 다른 프로세스를 종료해야 한다. 향후 릴리스에서는 이 문제를 우아하게 처리할 예정이다.

  5. 크롬 개발자 콘솔 열기
    아무 웹 페이지에서 마우스 오른쪽 버튼을 클릭하고 '검사'를 클릭하여 크롬 개발자 도구를 연다. 개발자 도구를 열면 MCP 클라이언트에서 로그에 접근할 수 있다.
    개발자 도구

    BrowserTools 패널에서 다음을 수행할 수 있다.

    • 수동으로 스크린샷 캡처
    • 스크린샷 저장 경로 정의 (기본값: Downloads/mcp-screenshots)
    • 저장된 모든 로그 지우기
    • 로그 크기 제한/잘림 수정

    참고: 페이지를 새로 고치거나 browser-tool-mcp 서버를 실행하는 Node.js 프로세스를 다시 시작할 때마다 서버의 로그가 지워진다. BrowserTools 패널에서 'Wipe Logs' 버튼을 클릭하여 수동으로 로그를 지울 수 있다.

축하한다! BrowserTools 설치 및 구성이 완료되었다.
새로운 MCP 도구 사용법은 Quickstart 가이드를 참조한다.

문제 해결

일반적인 문제와 해결 단계는 다음과 같다.

  1. Cursor에 MCP 서버가 올바르게 설치되었는지 확인한다.
  2. 새 터미널에서 @agentdeskai/browser-tools-server@1.2.0 명령어를 실행 중인지 확인한다.
  3. 크롬 확장 프로그램이 설치되어 있고, 로그를 캡처하려는 탭에서 크롬 개발자 도구가 열려 있는지 확인한다.
  4. 이 방법들이 효과가 없다면 아래의 일반적인 문제 및 오류 섹션을 다시 확인한다.

추가 문제가 있다면:

  1. 새 터미널에서 다음 명령어를 실행하여 Cursor MCP 로그를 모니터링한다.
    shell tail -n 20 -F ~/Library/Application\\ Support/Cursor/**/*.MCP.log
  2. 해당 로그, browser-tools-server의 Node.js 서버 로그, 그리고 가능하다면 설치된 확장 프로그램에 있는 오류 버튼(있는 경우)의 스크린샷을 찍는다.
  3. @tedx_ai에게 X를 통해 연락하거나, Github 리포지토리에 요청된 세부 정보와 함께 이슈를 추가한다. 가능한 한 빨리 답변을 줄 것이다.

일반적인 문제 및 오류

  • 오류: 스크린샷 도구 실패
    Cursor 및 일부 다른 MCP 클라이언트가 올바른 MCP 서버 버전을 항상 가져오지 못할 수 있다. 최신 작동 버전을 명시적으로 사용하려면 npx @agentdeskai/browser-tools-mcp@1.2.0을 사용한다.

  • 문제: 스크린샷을 볼 수 없음
    스크린샷은 기본적으로 다운로드 폴더 내의 /mcp-screenshots 디렉토리에 저장된다. 그곳에서 스크린샷을 확인한다. 그렇지 않으면 BrowserToolsMCP 개발자 도구 패널에서 스크린샷을 저장할 경로를 추가할 수 있다. 현재 프로젝트에 스크린샷 폴더를 만들고, 해당 폴더를 마우스 오른쪽 버튼으로 클릭한 후 '경로 복사'를 클릭한다. 그런 다음 개발자 도구 패널에 붙여넣고 Enter를 누른다.

  • 문제: 로그가 보이지 않음
    로그를 캡처하려는 브라우저 탭에서 크롬 개발자 도구 콘솔을 열어야 한다.

  • 문제: 너무 많은 로그가 보임
    크롬 개발자 도구가 열려 있는 다른 탭들을 모두 닫는다. BrowserToolsMCP는 여러 탭에서 로그를 캡처한다.

  • 문제: 로그가 계속 사라짐!
    페이지를 새로 고치거나 browser-tool-mcp 서버를 실행하는 Node.js 프로세스를 다시 시작할 때마다 로그가 지워진다.

  • browser-connector로 로그 전송 실패?
    다른 탭에 크롬 개발자 도구/검사기 창이 열려 있을 수 있다! 각 탭의 해당 패널을 닫고, 작업 중인 프로젝트 탭을 새로 고치면 이 문제가 해결될 것이다!

  • 문제: 알 수 없는 오류 발생
    @tedx_ai에게 연락하거나 Github 리포지토리에 이슈를 추가한다.

댓글

댓글 쓰기