Visual Browser Agent

로컬 우선(local-first) 브라우저 자동화 도구로, AI 에이전트에게 웹 상호작용을 위한 "눈과 손"을 제공합니다. Visual Browser Agent는 Playwright에 에이전트 제어 평면(control plane)을 더한 것입니다. Playwright가 브라우저 작업을 수행하고, 이 프로젝트는 MCP 도구, 시각적 증거(evidence), 승인(approval), Chrome 신원(identity) 처리, 안전 제어, 그리고 코딩 에이전트와 일상적인 브라우저 작업을 위한 워크플로우를 추가합니다.

설치 후 일어나는 일

Chromium, CDP, 원격 디버깅, 또는 Chrome의 내부 프로필 이름을 이해할 필요가 없습니다.

기술 설치 프로그램이 Visual Browser Agent를 사용 중인 코딩 에이전트에 등록하고 Playwright 브라우저 런타임을 설치합니다. 그 후에는 평소 워크플로우가 코딩 에이전트 채팅에서 진행됩니다. 다음과 같이 말할 수 있습니다:

Use the browser to open this website and check the layout.

에이전트는 먼저 기존 Chrome 세션이 사용 가능한지 확인합니다. 세션이 있으면 그 세션을 사용하고, 없으면 깨끗한 Playwright 관리 Chromium 세션을 시작합니다. 일반 언어로 명시적으로 지정할 수도 있습니다:

Use my Work Chrome account and check the dashboard.

에이전트는 "업무 — work@example.com", "개인 — personal@example.com"과 같은 친숙한 Chrome 신원을 발견합니다. 가능한 신원이 둘 이상이면 대화에서 선택하도록 요청합니다. 프로필 명령을 실행하거나 Profile 3을 선택할 필요가 없습니다.

Visual Browser Agent에는 선택적인 로컬 제어판도 포함되어 있습니다. 기술 사용자는 npx visual-browser-agent dashboard로 시작할 수 있지만, 제어판은 일반 사용에 필수는 아닙니다. 제어판은 http://127.0.0.1:8787/에서 연결 상태, 활성 탭, 사용 가능한 Chrome 신원, 최근 증거를 표시합니다.

에이전트가 로그인, 메시지 전송, 게시, 구매, 삭제, 제출, 또는 외부 데이터 변경을 수행하기 전에 일시 중지하고 승인을 요청합니다. 읽기 전용 검사, 스크린샷, 시각적 감사, 증거 캡처는 자동으로 진행될 수 있습니다.

Related MCP server: websight

작동 방식

두 개의 브라우저와 두 가지 연결 방법이 있습니다:

설치

옵션 1: 코딩 에이전트에게 설치 요청

Claude Code, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity 또는 기타 MCP 지원 코딩 에이전트에서 다음과 같이 요청하세요:

Install Visual Browser Agent, set it up for this coding agent, and check that the browser runtime is ready. Ask me before installing software or changing browser settings.

에이전트는 설정 상태를 확인하고, Playwright Chromium 설치 전에 확인을 요청하며, MCP 서버를 등록하고, 누락된 권한 또는 확장 프로그램 단계를 보고해야 합니다. 그런 다음 "브라우저를 사용해서 …"라고 말하기만 하면 됩니다.

옵션 2: GitHub에서 설치 (테스트 권장)

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install dependencies
npm install

# Build
npm run build

# Initialize (installs Chromium + MCP + skills)
npx visual-browser-agent init

또는 npx로 직접 사용:

npx github:Akakaui/visual-browser-agent init

옵션 3: npm에서 설치 (게시 후)

# Install globally
npm install -g visual-browser-agent

# Or use directly with npx
npx visual-browser-agent init

옵션 4: 로컬 개발

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install in development mode
npm install

# Build
npm run build

# Link for global use
npm link

# Now you can use it anywhere
visual-browser-agent init

빠른 시작

1. 초기화

npx visual-browser-agent init

이 명령은 다음을 수행합니다:

• Chromium(Playwright 브라우저) 설치

• MCP 구성 설정

• Agent Skills 설치

• 코딩 에이전트 자동 감지 및 래퍼 설치

2. 사용 시작

# Start MCP server with Chromium (default)
npx visual-browser-agent mcp

# Or start with Chrome extension
npx visual-browser-agent mcp --extension

3. AI 에이전트에서 사용

에이전트에게 "이 웹사이트의 디자인을 조사해줘"라고 요청하세요.

에이전트는 Visual Browser Agent를 사용하여 브라우저를 제어합니다.

기존 Chrome 사용 (확장 프로그램)

프로필 전환, 검증, 문제 해결을 포함한 일반 사용자용 전체 안내는 EXTENSION_INSTALLATION.md를 참조하세요.

에이전트가 기존 Chrome(로그인, 쿠키, 세션 포함)을 사용해야 하는 경우:

1. 확장 프로그램 설치

1. Chrome 열기 → chrome://extensions/

2. 개발자 모드 활성화

3. 압축 해제된 확장 프로그램 로드 클릭

4. 선택: node_modules/visual-browser-agent/browser-extension

2. 에이전트 시작

npx visual-browser-agent mcp --extension

3. AI 에이전트에서 사용

에이전트에게 "내 Gmail에 로그인해서 이메일을 요약해줘"라고 요청하세요.

에이전트는 모든 로그인이 유지된 상태로 사용자의 Chrome에 연결합니다.

AI 에이전트와의 통합

자동 감지 (권장)

npx visual-browser-agent init을 실행하면 자동으로:

• 사용 중인 코딩 에이전트 감지

• 적절한 래퍼 설치

• MCP 구성 설정

수동 설치

자동 감지가 작동하지 않으면 수동으로 설치할 수 있습니다:

# Install for specific agent
npx visual-browser-agent host <agent-name>

지원되는 에이전트:

• claude-code

• cursor

• gemini

• opencode

• antigravity

• windsurf

• cline

• roo

• kiro

• copilot

• codex

• goose

Claude Code

.claude/settings.json에 추가:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Cursor

.cursor/mcp.json에 추가:

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Chrome 확장 프로그램 모드용

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp", "--extension"]
    }
  }
}

AI 에이전트가 이를 사용하는 방법

시나리오 1: 공개 웹사이트 조사

에이전트 판단: "공개 웹사이트이므로 로그인이 필요 없음."

에이전트 수행: Chromium 사용 (기본값)

npx visual-browser-agent mcp

시나리오 2: 사용자 개인 데이터 접근

에이전트 판단: "사용자의 로그인이 필요함."

에이전트 수행: 확장 프로그램을 통해 Chrome 사용

npx visual-browser-agent mcp --extension

시나리오 3: 사용자가 브라우저 지정

사용자 말: "로그인된 내 업무용 Chrome 계정을 사용해줘"

에이전트 수행:

npx visual-browser-agent mcp --choose-profile

명령어 참조

일반 사용자용 제어판

비기술 사용자의 경우, 브라우저 에이전트는 관리자 또는 코딩 에이전트 설정 과정에서 한 번 설치 및 등록되어야 합니다. 그 후 사용자는 코딩 에이전트에서 "브라우저를 사용해서 이 웹사이트를 열어줘", "내 업무용 계정을 사용해줘", 또는 "페이지를 확인하고 스크린샷을 보여줘"라고 말하며 작업합니다. 에이전트는 MCP를 통해 연결, 신원 발견, 증거, 승인을 처리합니다.

선택적인 로컬 제어판은 연결 상태 확인 및 복구를 위해 제공됩니다. 기술 사용자는 npx visual-browser-agent dashboard로 시작할 수 있으며, http://127.0.0.1:8787/에서 열리고 연결 상태, 친숙한 Chrome 신원, 활성 탭, 최근 증거를 표시합니다. 제어판은 로컬 전용이며 코딩 에이전트 대화를 대체하지 않습니다.

Playwright 2.0 호환성 표면

Visual Browser Agent는 에이전트 워크플로우를 위해 Playwright 기반 MCP 표면을 제공합니다. 탐색, 양식, 업로드, 다운로드, 스크린샷, 녹화, 반응형 감사, 시각적 연구 외에도 에이전트는 탭/페이지, 기록, 드래그 앤 드롭, 로케이터 참조, 웹 우선 단언(web-first assertions), 프레임 검사, 대화 상자 정책, 쿠키, 승인된 저장 상태 내보내기, 최근 콘솔 메시지, 최근 네트워크 요청, URL 라우팅 목(mock), 추적(tracing), 미디어 에뮬레이션, PDF 증거, 확인 게이트 페이지 평가를 사용할 수 있습니다.

호환성 계층은 의도적으로 민감한 작업을 명시적으로 유지합니다. 쿠키 삭제에는 confirm=true가 필요하고, 페이지 평가에는 confirmDangerous=true가 필요하며, 공개 제출 및 아티팩트 삭제는 승인 서비스의 적용을 받습니다. 네트워크 목과 저장 아티팩트는 활성 에이전트 세션과 승인된 디렉토리로 제한됩니다.

프로필

Chrome 프로필이 여러 개인 경우 확장 프로그램에 사용할 로그인된 계정을 선택하세요:

# Choose an account interactively
npx visual-browser-agent mcp --choose-profile

# Advanced: use a known technical profile name
npx visual-browser-agent mcp --profile "Profile 3"

문제 해결

Chromium이 작동하지 않음

npx playwright install chromium

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

1. Chrome이 열려 있는지 확인

2. 확장 프로그램 아이콘에 "ON"이 표시되는지 확인

3. 실행: npx visual-browser-agent doctor

MCP 서버가 시작되지 않음

# Check environment
npx visual-browser-agent doctor

# Reinstall
npx visual-browser-agent init

아키텍처

User's AI Agent (Claude Code, Cursor, etc.)
                    |
                    | MCP Protocol
                    |
        Visual Browser Agent MCP Server
                    |
        +-----------+-----------+
        |                       |
    Chromium                  Chrome
    (Playwright)            (Extension)
        |                       |
        v                       v
  Agent controls           Agent connects
  fresh browser            to existing browser

라이선스

MIT

비기술 사용자를 위한 일상 사용

Visual Browser Agent는 두 가지 간단한 모드로 사용할 수 있습니다:

비기술 사용자는 MCP를 이해할 필요가 없습니다. 한 번 설정한 후에는 코딩 에이전트에게 일반 언어로 원하는 것을 말하면 됩니다. 예: "업무용 Chrome 프로필을 열고, 이 URL의 결제 페이지를 검사하고, 스크린샷을 저장해줘" 또는 "깨끗한 Chromium 세션을 사용해서 이 웹사이트를 데스크톱과 모바일에서 비교해줘." 래퍼는 코딩 에이전트에게 브라우저 연결 확인, 적절한 모드 선택, 인증 또는 중대한 작업 전에 질문, 증거와 함께 간결한 결과 반환을 지시합니다.

Chrome 프로필: 확장 프로그램 대 원격 디버깅

Chrome 확장 프로그램은 Chrome 프로필별로 설치되며, 모든 브라우저 창에 한 번 설치되는 것이 아닙니다. 확장 프로그램 모드로 세 개의 별도 Chrome 프로필을 사용하려면 각 프로필을 열고 chrome://extensions/로 이동하여 개발자 모드를 활성화하고 각 프로필에서 한 번씩 압축 해제된 browser-extension/ 디렉토리를 로드해야 합니다. 동일한 확장 프로그램 소스를 모든 프로필에 로드할 수 있지만, 각 프로필은 자체 권한을 부여해야 하며 해당 프로필이 선택될 때 열려 있어야 합니다.

원격 디버깅은 다릅니다. 특정 --profile-directory와 디버깅 포트로 시작된 Chrome 인스턴스에 연결합니다. 대부분의 사용자는 visual-browser-agent mcp --choose-profile을 실행해야 합니다. 이 도구는 Chrome에서 친숙한 계정 레이블을 읽고 사용자가 번호로 선택할 수 있게 합니다. 기술적인 --profile 옵션은 스크립트와 고급 설정을 위해 계속 제공됩니다. 다른 Chrome 프로세스에서 이미 사용 중인 프로필은 두 번째 실행을 거부할 수 있습니다. 해당 프로필을 먼저 닫거나 별도의 디버깅 프로필과 포트를 사용하세요.

기존 로그인 쿠키가 필요한 사용자에게는 확장 프로그램 경로가 일반적으로 가장 간단합니다. 반복 가능한 깨끗한 브라우저가 필요한 사용자에게는 Chromium이 더 안전합니다. 원격 디버깅은 선택한 브라우저 세션을 로컬 에이전트 프로세스에 노출시키므로 고급 옵션으로 취급해야 합니다.

프롬프트로 브라우저 에이전트 선택하기

사용자는 일반적으로 브라우저 모드나 전문가 모델이 아닌 작업을 선택합니다. Claude, Cursor, Copilot, Codex, Gemini, Windsurf, Cline, Roo, Kiro, Goose, OpenCode, Antigravity 또는 MCP를 지원하는 다른 코딩 에이전트에서 "브라우저를 사용하여 …"라고 말하세요. 래퍼는 에이전트에게 자동 브라우저 선택을 사용하고, 필요할 때 표시되는 Chrome 프로필을 발견하며, 기존 세션이 없을 때 관리형 Chromium으로 대체하도록 지시합니다. 코딩 에이전트는 통합이 설치된 후 Visual Browser Agent MCP 도구를 선택합니다. 프롬프트는 중요할 때 세션 요구 사항을 명시해야 합니다:

Use a clean Chromium browser. Audit this public website at desktop and mobile widths and save visual evidence.

Use the Work account I choose from Chrome. Open the internal dashboard, inspect the layout, and ask me before making any changes.

Use the current browser session. Do not submit forms, publish, purchase, delete, or send messages without asking for approval first.

팀이 명명된 브라우저 전문가를 원한다면 코딩 클라이언트용으로 visual-browser-agent host <agent-name>을 실행하고 생성된 MCP 구성과 래퍼를 해당 프로젝트에 유지하세요. 패키지에는 Claude Code, Cursor, Gemini, Windsurf, Cline, Roo, Kiro, Copilot, Codex, Goose, OpenCode, Antigravity용 어댑터가 포함되어 있으며, 전용 래퍼가 없는 호스트에는 범용 래퍼를 사용합니다. 새 호스트는 동일한 표준 MCP 구성을 사용할 수 있습니다: visual-browser-agent mcp --managed 명령을 시작하고 visual-browser라는 이름의 MCP 서버로 등록하세요.

권장 첫 설정

npm install
npm run build
npx visual-browser-agent init --mode chromium
npx visual-browser-agent host <your-coding-agent>

그런 다음 코딩 에이전트를 다시 시작하고 시각적 브라우저 도구를 사용하도록 요청하세요. 깨끗한 일일 Chromium 워크플로우를 위해 visual-browser-agent mcp --managed를 사용하세요. 기존 Chrome 프로필의 경우 원하는 프로필에 확장 프로그램을 로드한 후 visual-browser-agent mcp --choose-profile을 사용하세요. 고급 스크립트에서만 --profile을 사용하세요.

에이전트는 웹사이트를 검토할 때 항상 읽기 전용 검사와 스크린샷을 자동으로 사용해야 합니다. 게시, 발행, 구매, 삭제, 제출 또는 외부 데이터 변경 전에 명시적 승인을 요청해야 합니다. 인증 및 개인 정보는 프롬프트나 구성 파일에 넣지 말고 사용자가 브라우저에서 직접 제공해야 합니다.

에이전트 아티팩트, 아티팩트 패널, 질문 및 승인

완전한 일반 사용자 및 기술 워크플로우는 Visual Browser Agent 1.0 사용자 가이드를 읽으세요. 간단히 말하면 코딩 에이전트는 MCP를 통해 Visual Browser Agent와 상호 작용합니다: 사용 가능한 브라우저 도구를 발견하고, 사용자 요청에 맞는 도구를 선택하며, 텍스트, 구조화된 JSON, 스크린샷 및 증거 메타데이터를 받습니다.

Visual Browser Agent는 UI 기반 코딩 에이전트와 CLI 기반 에이전트 모두를 위해 설계되었습니다. Claude Code 또는 Antigravity와 같은 UI 호스트는 스크린샷/이미지 콘텐츠와 생성된 HTML 또는 Markdown 증거 보고서를 아티팩트 패널에 배치할 수 있습니다. CLI 호스트 또는 일반 MCP 클라이언트는 포함된 이미지 블록, 구조화된 메타데이터, 로컬 증거 경로 또는 http://127.0.0.1:8787/의 로컬 대시보드를 통해 동일한 결과를 사용할 수 있습니다. 에이전트는 호스트가 임의의 샌드박스 경로를 열 수 있다고 가정해서는 안 됩니다. 휴대 가능한 결과와 대체 수단을 반환해야 합니다.

좋은 브라우저 에이전트 결과에는 작업 목표, URL 및 출처, 선택된 브라우저 프로필, 수행된 작업, 검증(assertions), 스크린샷, 콘솔/네트워크 발견 사항, 실행 ID, 타임스탬프 및 다음 단계가 포함됩니다. 이를 통해 사용자는 원시 도구 로그를 읽는 대신 작업을 시각적으로 검증할 수 있습니다. 필요할 때 에이전트에게 이를 명시적으로 요청하세요:

Create a host-renderable visual report with screenshots, assertions, console errors, and a concise conclusion. Also provide a local fallback.

인간 상호 작용에는 세 가지 유형이 있습니다. 질문은 사용할 Chrome 프로필이나 탭과 같은 누락된 정보를 해결합니다. 인간 인계(human takeover) 는 비밀번호, MFA 프롬프트, CAPTCHA 또는 일회용 코드가 나타날 때 사용자에게 브라우저를 직접 조작하도록 요청합니다. 승인은 전송, 게시, 구매, 삭제 또는 제출과 같은 중대한 작업을 승인합니다. 이들은 의도적으로 분리되어 있습니다: 질문은 행동 허가가 아니며, 스크린샷은 거래 성공의 증거가 아닙니다.

대체 ask_human 도구는 질문과 간단한 구조화된 선택을 지원합니다. request_approval 및 submit_public_action 도구는 명시적 승인을 위해 예약되어 있습니다. 에이전트는 승인을 요청하기 전에 정확한 사이트, 대상, 작업 및 관련 데이터를 표시해야 하며, 거부를 조용히 재시도하는 대신 최종 사용자 결정으로 처리해야 합니다. 비밀번호, API 키, 액세스 토큰, 결제 정보 또는 일회용 코드를 에이전트 대화에 붙여넣지 마세요. 전체 안전 모델은 docs/user-guide-1.0.md를, 프로필별 Chrome 확장 프로그램 설정은 EXTENSION_INSTALLATION.md를 참조하세요.