MCP 브라우저 사용

이 MCP로 할 수 있는 것

이 프로젝트는 AI 에이전트가 Model Context Protocol(MCP)과 Selenium을 사용하여 웹 사용, 브라우저 자동화, 스크래핑 및 자동화 작업을 수행할 수 있도록 지원하는 것을 목표로 합니다.

이 MCP의 특별한 점은 여러 에이전트가 여러 브라우저 창에 액세스하는 것을 처리할 수 있다는 것입니다. 여러 스크래핑 에이전트를 실행하기 위해 여러 Docker 이미지, VM 또는 컴퓨터를 시작할 필요가 없습니다. 또한 모든 에이전트에서 하나의 단일 브라우저 프로필을 계속 사용할 수 있습니다. 각 에이전트는 고유한 창을 가지며 서로 간섭하지 않습니다.

이로 인해 여러 에이전트 처리가 원활해집니다. 원하는 만큼 에이전트를 시작하기만 하면 바로 작동합니다! 두 개의 Claude Code 인스턴스, 하나의 Codex CLI 인스턴스, 하나의 Gemini CLI 인스턴스 및 fast-agent 인스턴스를 모두 한 컴퓨터에서, 모두 동일한 브라우저 프로필을 사용하여 (어느 정도) 병렬로 작업할 수 있습니다.

우리의 사명은 AI 에이전트가 자연어 지침을 기반으로 최소한의 인간 감독만으로 모든 웹 작업을 완료할 수 있도록 하는 것입니다.

Related MCP server: Selenium MCP Server

주요 기능

• HTML 잘라내기(Truncation): 이 MCP를 사용하면 HTML 페이지의 잘라내기를 구성할 수 있습니다. 다른 스크래핑 MCP는 컨텍스트 창보다 큰 접근성 스냅샷이나 HTML 덤프로 AI를 압도할 수 있습니다. 이 MCP는 MCP_MAX_SNAPSHOT_CHARS 환경 변수를 설정하여 최대 페이지 크기를 관리하도록 도와줍니다.

• 다중 브라우저 창 및 다중 에이전트: 에이전트 측의 조정 없이 여러 에이전트를 이 MCP에 독립적으로 연결할 수 있습니다. 각 에이전트는 동일한 브라우저 프로필로 작업할 수 있으며, 이는 에이전트 간에 로그인이 유지되어야 할 때 유용합니다. 각 에이전트는 고유한 브라우저 창을 가지므로 서로 간섭하지 않습니다. 브라우저 창을 식별하기 위해 Chrome DevTools Protocol TargetId를 사용합니다.

알려진 제한 사항

• Iframe 컨텍스트: iframe 내의 다단계 상호 작용은 각 작업에 대해 iframe_selector를 지정해야 합니다. 안정성을 위해 브라우저 컨텍스트는 각 도구 호출 후에 재설정됩니다. iframe 워크플로의 경우 각 click_element, fill_text 또는 debug_element 호출에서 iframe 선택기 매개변수를 반복하십시오.

구성 / 설치

1. 복제 및 가상 환경 생성

git clone https://github.com/janspoerer/mcp_browser_use.git
cd mcp_browser_use
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Chrome Beta 설치

AI 에이전트가 일상적인 브라우징을 방해하지 않고 원격 디버깅으로 실행될 수 있도록 일반 Chrome이 아닌 Chrome Beta를 사용하는 것을 권장합니다.

macOS:

brew install --cask google-chrome-beta

Ubuntu / Debian:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" \
    | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-beta

Windows: google.com/chrome/beta에서 Chrome Beta를 다운로드하여 설치하십시오.

설치 후 확인:

google-chrome-beta --version      # Linux
# or
"/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta" --version  # macOS

Linux 헤드리스 서버 — Xvfb (가상 디스플레이)

Chrome은 디스플레이가 필요합니다. 헤드리스 Linux 서버(GUI 없음)에서는 Xvfb를 사용하십시오:

sudo apt install -y xvfb

# Start a virtual display on screen :99
Xvfb :99 -screen 0 1920x1080x24 &

# Tell Chrome which display to use
export DISPLAY=:99

영구적으로 적용하려면 .bashrc 또는 .profile에 export DISPLAY=:99를 추가하십시오.

3. 구성 및 시작

• Chrome Beta를 설치한 후 아래의 환경 변수 구성 섹션에 설명된 대로 .mcp.json에서 Chrome Beta 실행 파일을 가리키십시오.

• MCP 서버를 시작하십시오(방법을 모르는 경우 아래의 "이 MCP 사용 방법" 섹션을 확인하십시오).

이 MCP 사용 방법

modelcontextprotocol.io의 MCP 문서를 참조하십시오.

MCP 구성 파일이 가리키는 Python 환경에 모든 종속성을 설치해야 합니다. 예를 들어 python 또는 python3 실행 파일을 가리키면 전역 Python 환경을 가리키게 됩니다. 일반적으로 다음과 같은 가상 환경을 가리키는 것이 좋습니다:

/Users/yourname/code/mcp_browser_use/.venv/bin/python

이 저장소를 로컬 code 폴더에 복제한 경우 MCP 구성 파일은 다음과 같아야 합니다:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

그리고 (macOS의 경우) /Users/janspoerer/Library/Application Support/Claude/claude_desktop_config.json에 위치합니다.

설치해야 할 종속성을 확인하려면 requirements.txt를 참조하십시오.

Claude를 다시 시작하여 JSON 구성이 유효한지 확인하십시오. 문제가 있으면 Claude가 MCP에 대한 오류 로그로 안내합니다.

설정이 성공하면 Claude의 "새 채팅" 창 오른쪽 하단에 작은 망치 아이콘이 표시됩니다. 망치 옆에는 MCP가 제공하는 기능의 수가 표시됩니다.

망치를 클릭하여 사용 가능한 도구를 확인하십시오.

환경 변수 구성

중요: 모든 환경 변수는 .env 파일이 아닌 프로젝트 루트 .mcp.json 파일에 정의하십시오. 이렇게 하면 충돌 없이 단일 정보 소스를 보장할 수 있습니다.

권장 구성 (Chrome Beta)

.mcp.json 파일의 env 섹션에 환경 변수를 추가하십시오:

{
  "mcpServers": {
    "mcp_browser_use": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_browser_use"],
      "env": {
        "BETA_PROFILE_NAME": "SeleniumProfile",
        "BETA_EXECUTABLE_PATH": "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
        "BETA_PROFILE_USER_DATA_DIR": "/Users/yourname/Library/Application Support/Google/Chrome Beta",
        "CHROME_REMOTE_DEBUG_PORT": "9225",
        "MCP_HEADLESS": "0",
        "MCP_ENABLE_EXTENSIONS": "1",
        "MAX_SNAPSHOT_CHARS": "10000"
      }
    }
  }
}

Windows 예시:

"env": {
  "BETA_PROFILE_NAME": "SeleniumProfile",
  "BETA_EXECUTABLE_PATH": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
  "BETA_PROFILE_USER_DATA_DIR": "C:\\Users\\yourname\\AppData\\Local\\Google\\Chrome Beta\\User Data",
  "CHROME_REMOTE_DEBUG_PORT": "9225",
  "MCP_HEADLESS": "0",
  "MCP_ENABLE_EXTENSIONS": "1"
}

환경 변수 참조

왜 Chrome Beta를 사용하나요?

Chrome Beta(또는 Canary)를 사용하면 일반 Chrome 브라우저와의 충돌을 방지할 수 있습니다:

• AI 에이전트는 원격 디버깅이 활성화된 상태에서 Chrome을 실행해야 합니다

• 일반 Chrome 인스턴스는 원격 디버깅으로 실행할 수 없습니다

• Chrome Beta를 사용하면 동일한 시스템에서 둘 다 공존할 수 있습니다

프로필 권장 사항

• "Default"가 아닌 "SeleniumProfile"과 같은 전용 프로필을 사용하십시오

• 이렇게 하면 Chrome Beta를 수동으로 열 때 충돌을 방지할 수 있습니다

• 확장 프로그램과 로그인은 세션 전반에 걸쳐 이 프로필에 유지됩니다

• 각 AI 에이전트는 고유한 브라우저 창을 가지지만 프로필을 공유합니다

사용 가능한 도구

디버깅

기본 브라우저(자동화된 브라우저가 아님)에서 이 URL을 방문하여 브라우저가 실행 중인지 확인하십시오:

http://127.0.0.1:9223/json/version

브라우저가 실행 중이면 다음과 같이 표시됩니다:

{
   "Browser": "Chrome/140.0.7339.24",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
   "V8-Version": "14.0.365.3",
   "WebKit-Version": "537.36 (@f8765868e23d9ee5209061fc999f6495c525cd13)",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/d8f511eb-947c-4eb1-833d-917212a92394"
}

잠금 파일 및 조정

이 MCP는 파일 기반 잠금을 사용하여 동일한 브라우저 프로필에 액세스하는 여러 에이전트를 조정합니다. 모든 잠금 파일은 쉽게 검사할 수 있도록 프로젝트 루트 디렉토리의 tmp/mcp_locks/에 저장됩니다.

잠금 파일 유형

작업 잠금 (<hash>.softlock.json 및 <hash>.softlock.mutex)

• 한 번에 하나의 에이전트만 브라우저 작업을 수행할 수 있도록 보장합니다

• 기본 TTL: 30초 (MCP_ACTION_LOCK_TTL을 통해 구성 가능)

• 에이전트가 작업하는 동안 하트비트로 자동 갱신됨

• 에이전트는 잠금을 획득하기 위해 최대 60초까지 대기함 (MCP_ACTION_LOCK_WAIT를 통해 구성 가능)

창 레지스트리 (<hash>.window_registry.json)

• 어떤 에이전트가 어떤 브라우저 창을 소유하고 있는지 추적합니다

• 포함 내용: targetId, windowId, 프로세스 PID, 마지막 하트비트 타임스탬프

• 고아 정리용: 충돌/정지된 에이전트의 창을 자동으로 닫음

• 정지 임계값: 5분 (MCP_WINDOW_REGISTRY_STALE_SECS를 통해 구성 가능)

시작 뮤텍스 (<hash>.startup.mutex)

• 프로필당 단일 브라우저 인스턴스 시작을 보장합니다

• 초기 Chrome 프로세스 시작 조정 중에 사용됨

파일 형식: <hash>는 Chrome 프로필의 user_data_dir 및 profile_name에서 파생된 SHA-256 해시로, 프로세스 전반에서 안정적인 식별을 보장합니다.

구성

다음 환경 변수로 잠금 동작을 사용자 지정할 수 있습니다:

# Lock directory (default: <project_root>/tmp/mcp_locks/)
MCP_BROWSER_LOCK_DIR=/path/to/locks

# Action lock TTL in seconds (default: 30)
MCP_ACTION_LOCK_TTL=30

# Max wait time for action lock in seconds (default: 60)
MCP_ACTION_LOCK_WAIT=60

# Window registry stale threshold in seconds (default: 300)
MCP_WINDOW_REGISTRY_STALE_SECS=300

# File mutex stale threshold in seconds (default: 60)
MCP_FILE_MUTEX_STALE_SECS=60

고아 창 정리

에이전트가 브라우저 세션을 시작하면 자동으로 다음을 수행합니다:

1. 죽은 프로세스(PID가 더 이상 존재하지 않음)의 항목에 대해 창 레지스트리를 확인합니다

2. 정지된 항목(5분 이상 하트비트 없음)을 확인합니다

3. Chrome DevTools Protocol을 통해 고아 창을 닫습니다

4. 레지스트리 항목을 정리합니다

이렇게 하면 충돌하거나 종료된 에이전트가 좀비 브라우저 창을 열어두지 않도록 합니다.

데모 영상 (YouTube)

테스트 실행

pytest-asyncio를 사용하지 않습니다.

pip install -e ".[test]"`