agent-browser-mcp

에이전트가 "당신이 사용 중인 실제 Chrome"을 직접 조작할 수 있게 해주는 MCP 서비스입니다.

샌드박스 브라우저나 단순한 웹 스크래퍼가 아니라, 로컬에 이미 열려 있는 Chrome에 연결하여 다음을 유지합니다:

로그인 상태
쿠키
열려 있는 탭
실제 페이지 컨텍스트

다음과 같은 시나리오에 적합합니다:

Hermes가 샤오홍슈(小红书), 백엔드 시스템, 지식 베이스, 관리자 페이지를 직접 읽게 할 때
상태가 없는 브라우저에 다시 로그인할 필요 없이 이미 로그인된 웹사이트를 자동화할 때
일반 브라우저 자동화가 불안정할 때 CDP / 실제 마우스 및 키보드 조작으로 전환할 때
하나의 MCP 도구에서 페이지 스캔, JS 실행, CDP 제어, 스크린샷, 물리적 입력을 모두 사용할 때

한 문장 요약:

이 프로젝트는 "실제 브라우저 자동화"를 표준 MCP로 패키징하여, 에이전트가 샌드박스 브라우저만 조작하는 것이 아니라 사용자의 일상적인 브라우저 워크플로우에 직접 진입할 수 있도록 합니다.

핵심 기능 요약

실제 Chrome 탭 발견 및 전환
페이지 스캔 및 단순화된 콘텐츠 추출
페이지 내 JavaScript 실행
네이티브 CDP 단일 명령 / 배치 호출
페이지 스크린샷 / 데스크톱 스크린샷
쿠키 읽기
마우스 이동, 클릭, 드래그
키보드 입력 및 단축키

Hermes, Claude Desktop, Cursor 등 MCP 클라이언트가 로컬의 실제 브라우저를 직접 조작하게 하려면 이 프로젝트가 적합합니다.

이 MCP로 할 수 있는 일

이 프로젝트는 실제 브라우저 자동화 기능을 표준 MCP 도구로 패키징했으며, 주요 기능은 다음과 같습니다:

1. 브라우저 탭 및 탐색

현재 연결된 실제 탭 확인
지정된 탭으로 전환
현재 탭에서 URL 열기
새 탭 열기

2. 페이지 읽기

현재 페이지 콘텐츠 스캔
단순화된 HTML / 텍스트 추출
정보 피드, 게시물 목록, 검색 결과 페이지 읽기에 적합

3. 페이지 실행 및 CDP 제어

페이지에서 임의의 JavaScript 실행
Chrome DevTools Protocol(CDP) 직접 호출
단일 명령 및 배치 명령 지원
스크린샷, DOM 쿼리, 클릭, 파일 업로드 등 복잡한 작업에 사용 가능

4. 스크린샷 기능

페이지 스크린샷 (CDP를 통해)
데스크톱 스크린샷 (실제 데스크톱 조작 보조용)

5. 실제 물리적 입력

마우스 이동
마우스 클릭
마우스 드래그
키보드 입력
단축키 전송

이러한 기능은 다음을 처리하는 데 매우 유용합니다:

로그인 상태 유지가 필수인 웹사이트
일반 브라우저 자동화 도구가 차단하기 쉬운 웹사이트
실제 클릭 / 실제 키보드 입력이 필요한 시나리오
복잡한 페이지 구조를 읽어야 하는 시나리오

적합한 시나리오

예시:

Hermes를 사용하여 현재 샤오홍슈 홈 추천 피드 읽기
실제 브라우저에서 백엔드 페이지를 열고 정보 수집
CDP를 호출하여 페이지 스크린샷 촬영
페이지 JS로 부족할 때 실제 마우스/키보드 조작으로 대체
상태가 없는 브라우저에 다시 로그인하는 대신, 이미 로그인된 웹사이트를 에이전트가 직접 조작하게 하기

작동 원리

프로젝트는 세 가지 계층으로 구성됩니다:

Chrome 확장 프로그램

실제 웹페이지에 주입
Chrome API를 통해 tabs / cookies / debugger / management에 액세스
로컬 브리지 서비스와 통신

TMWebDriver 로컬 브리지

기본 리스닝:
- WebSocket: 127.0.0.1:18765
- HTTP: 127.0.0.1:18766
확장 프로그램 연결, 세션 유지, 실행 결과 전달 담당

MCP 서비스

브라우저 기능을 MCP 도구로 노출
Hermes, Claude Desktop, Cursor 등 클라이언트가 직접 호출

주요 도구

현재 노출된 주요 MCP 도구는 다음과 같습니다:

브라우저/탭

get_setup_status
list_tabs
switch_tab
open_url
open_new_tab
extension_path
list_extensions

페이지 읽기/실행

scan_page
execute_js

CDP 및 스크린샷

cdp_command
cdp_batch
get_cookies
capture_page_screenshot
capture_desktop_screenshot

물리적 입력

mouse_move
mouse_click
mouse_drag
type_text
hotkey
pointer_info

설치 요구 사항

권장 환경:

macOS 또는 Windows
Python 3.10+
Google Chrome
MCP를 지원하는 모든 클라이언트 (예: Hermes Agent, Claude Desktop, Cursor)

설치

로컬에서 클론 후 실행:

cd agent-browser-mcp
pip install -e .

휠(wheel)을 먼저 빌드한 후 설치하려면:

python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl

명령줄 도구

설치 후 CLI가 제공됩니다:

agent-browser-mcp

다음과 같은 일반적인 하위 명령이 있습니다:

Chrome 확장 프로그램 디렉토리 출력

agent-browser-mcp extension-path

Hermes 구성 조각 출력

agent-browser-mcp print-hermes-config

환경 진단

agent-browser-mcp doctor

이 명령은 다음을 확인하는 데 도움이 되는 JSON을 출력합니다:

확장 프로그램 디렉토리 위치
config.js 생성 여부
포트 상태
현재 연결된 탭 수
다음 단계 제안

Chrome 확장 프로그램 설치

이 프로젝트에는 압축 해제된(unpacked) Chrome 확장 프로그램이 포함되어 있으며, 한 번 수동으로 로드해야 합니다.

1단계: 확장 프로그램 디렉토리 가져오기

agent-browser-mcp extension-path

2단계: Chrome에서 로드

다음 주소로 이동:

chrome://extensions

그 다음:

"개발자 모드" 켜기
"압축 해제된 확장 프로그램을 로드합니다" 클릭
이전 단계에서 출력된 디렉토리 선택

3단계: 일반 웹페이지 열기

about:blank 상태에 머물지 않도록 주의하세요.

Chrome에서 일반 웹페이지를 여세요 (예: https://www.baidu.com, https://www.xiaohongshu.com).

그렇지 않으면 유효한 세션이 생성되지 않습니다.

Hermes 구성

다음 내용을 ~/.hermes/config.yaml에 추가하세요:

mcp_servers:
  agent_browser:
    command: agent-browser-mcp
    timeout: 120
    connect_timeout: 60

프로젝트에 예제 파일도 포함되어 있습니다:

examples/hermes-config.yaml

구성 후 Hermes를 재시작하거나 MCP를 다시 로드하세요.

다음 명령으로 확인할 수 있습니다:

hermes mcp list
hermes mcp test agent_browser

테스트가 성공하면 Hermes가 이러한 브라우저 도구를 발견하고 호출할 수 있습니다.

Claude Desktop / Cursor 구성

저장소에 예제가 포함되어 있습니다:

examples/claude-desktop-config.json
examples/cursor-mcp.json

구성 구조는 매우 간단하며 핵심은 다음과 같습니다:

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

일반적인 사용 흐름

Python 패키지 설치
Chrome에서 확장 프로그램 로드
실제 웹페이지 열기
MCP 클라이언트에서 이 서비스 연결
브라우저 도구 호출 시작

예를 들어, 에이전트는 다음을 수행할 수 있습니다:

샤오홍슈 홈 열기
추천 피드 읽기
게시물 목록 스캔
페이지 CDP 스크린샷 촬영
필요 시 실제 마우스/키보드 조작 실행

보안 주의사항

이 프로젝트는 사용자의 실제 브라우저와 실제 데스크톱을 조작합니다.

즉:

마우스 이동이 실제로 발생합니다.
클릭이 실제로 발생합니다.
입력이 실제로 발생합니다.
단축키가 실제로 전송됩니다.
브라우저 내 로그인 상태도 실제입니다.

신뢰할 수 있는 MCP 클라이언트 및 에이전트 환경에서만 사용하십시오.

자주 묻는 질문

1. Hermes가 MCP 서비스는 보지만 탭에 연결되지 않음

다음 사항을 확인하세요:

chrome://extensions에서 확장 프로그램이 로드되었는지
Chrome에서 일반 웹페이지가 열려 있는지
about:blank에 머물러 있지는 않은지

다음 명령을 실행할 수도 있습니다:

agent-browser-mcp doctor

2. `connected_tabs`가 0임

보통 다음 이유 중 하나입니다:

확장 프로그램이 성공적으로 로드되지 않음
현재 일반 웹페이지가 없음
확장 프로그램이 방금 다시 로드되어 페이지가 아직 새로고침되지 않음

제안:

현재 웹페이지 새로고침
새 일반 URL 열기
doctor 명령 다시 실행

3. macOS에서 물리적 입력이 작동하지 않음

터미널 / MCP 클라이언트에 시스템 권한을 부여하세요:

손쉬운 사용(Accessibility)
화면 기록(데스크톱 스크린샷이 필요한 경우)

4. `hermes mcp test agent_browser` 실패