SeleniumBase MCP Server

SeleniumBase 브라우저 자동화를 Model Context Protocol을 통한 도구로 노출하므로, 모든 MCP 클라이언트(Claude Desktop, Claude Code 등)가 실제 브라우저를 구동할 수 있습니다.

이 폴더에는 세 가지 서버 변형이 있습니다:

세 서버 모두 기본값은 headless=False입니다. 세션 시작 시 headless=True를 전달하지 않으면 브라우저 창이 보입니다.

MCP 클라이언트 설정에서 작업에 맞는 *_server.py를 가리키세요(아래 3단계 참조) — 또는 세 개 모두 다른 이름으로 등록하세요.

1. 설치

(Python 3.10+ 및 uv 필요)

git clone https://github.com/seleniumbase/seleniumbase-mcp.git
cd seleniumbase-mcp
uv sync

uv sync는 pyproject.toml을 읽고 이 폴더에 .venv/를 만든 다음 두 의존성(mcp[cli], seleniumbase)과 이 프로젝트 자체를 설치합니다 — 이 프로젝트는 [project.scripts]를 통해 세 개의 콘솔 스크립트 명령을 등록합니다:

• seleniumbase-driver

• seleniumbase-cdp

• seleniumbase-sb

각각 해당 서버 파일의 main() 함수(mcp.run(transport="stdio"))만 호출합니다. 이 덕분에 uv run <name> — python 경로, venv 경로, 스크립트 경로 없이 — 아래 3단계와 4단계에서 MCP 클라이언트 명령으로 작동합니다.

# SeleniumBase's Driver() and SB() formats need a browser driver downloaded:
uv run seleniumbase get chromedriver
# (Not needed for the "seleniumbase-cdp" Pure CDP Mode MCP Server,
#  which doesn't use WebDriver at all.)

(uv가 없나요? 일반 python3 -m venv venv && pip install -e .도 동일하게 작동합니다 — 아래 모든 곳에서 uv run <name> 대신 python <script>.py를 사용하고, MCP 클라이언트 설정에는 경로 없는 옵션 대신 절대 경로 venv/bin/python + 스크립트 경로를 사용하세요.)

Related MCP server: gotham-browser

2. 단독 실행해 보기(선택적 확인)

uv run mcp dev cdp_server.py

그러면 SeleniumBase의 "Pure CDP 모드" MCP 서버용 MCP Inspector가 열리고, 명령("도구")을 테스트할 수 있습니다. Ctrl+C로 종료합니다. 실제 테스트는 클라이언트에 연결하는 것입니다(다음 단계).

3. Claude Desktop에 연결

Claude Desktop은 Claude Code처럼 "프로젝트" 디렉터리에서 실행되지 않으므로, 단순한 uv run <name>이 이 저장소를 찾는다는 보장이 없습니다. 안정적인 설정을 얻는 두 가지 방법이 있습니다:

옵션 A — 전역 설치(권장, 어디에도 경로 없음):

uv tool install .          # from inside the repo, installs the 3 commands globally

이렇게 하면 seleniumbase-driver/seleniumbase-cdp/seleniumbase-sb가 PATH에 영구적으로 등록됩니다(바이너리 디렉터리가 PATH에 없다는 경고가 나오면 uv tool ensurepath를 한 번 실행하세요). 그러면 claude_desktop_config.json은 다음과 같이만 하면 됩니다:

{
  "mcpServers": {
    "seleniumbase-cdp": { "command": "seleniumbase-cdp" },
    "seleniumbase-driver": { "command": "seleniumbase-driver" },
    "seleniumbase-sb": { "command": "seleniumbase-sb" }
  }
}

옵션 B — uv가 저장소를 직접 가리키게 하기(절대 경로 하나지만, venv/인터프리터 경로를 추적할 필요가 없고 별도 설치 단계도 없음):

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/seleniumbase-mcp", "run", "seleniumbase-sb"]
    }
  }
}

claude_desktop_config.json의 위치는 시스템에 따라 다릅니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop을 다시 시작하세요. 🔨 도구 아이콘이 표시되어 서버가 연결되었음을 알리고, start_browser, navigate, click 등의 도구를 사용할 수 있습니다. 실제로 필요한 항목만 유지하세요 — 하나만 필요하다면 브라우저 자동화 서버 세 개는 너무 많습니다.

4. Claude Code에 연결

이 저장소의 .mcp.json은 체크인되어 있으며 수정 없이 바로 사용할 수 있습니다 — uv run <name>이 현재 디렉터리의 pyproject.toml에서 이 프로젝트를 해석하므로 경로 편집이 필요 없습니다:

{
  "mcpServers": {
    "seleniumbase-cdp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-cdp"]
    },
    "seleniumbase-driver": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-driver"]
    },
    "seleniumbase-sb": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "seleniumbase-sb"]
    }
  }
}

Claude Code는 claude를 실행하는 디렉터리에서 .mcp.json을 자동으로 로드하므로, 이 저장소(또는 복제본) 안에서 claude를 실행하기만 하면 그대로 작동합니다 — 저장소를 복제한 모든 팀원에게 동일하게, 머신별 편집 없이 작동합니다.

.mcp.json에 의존하지 않고 서버를 수동으로 등록하려면:

claude mcp add seleniumbase-cdp -- uv run seleniumbase-cdp
claude mcp add seleniumbase-driver -- uv run seleniumbase-driver
claude mcp add seleniumbase-sb -- uv run seleniumbase-sb

(위와 같은 이유로 저장소 디렉터리 안에서 실행하세요.)

노출되는 도구 (driver_server.py)

설계 참고 사항 / 사용 사례에 맞게 조정할 사항

• 단일 전역 세션. 각 서버는 한 번에 하나의 브라우저 세션만 유지합니다. 이는 MCP 서버가 일반적으로 실행되는 방식(클라이언트 연결당 하나의 프로세스)과 일치하며 도구 표면을 단순하게 유지합니다. 여러 동시 브라우저 탭/세션이 필요하다면 명명된 세션의 dict로 확장하고 각 도구에 session_id 매개변수를 추가해야 합니다.

• 차단 호출. SeleniumBase의 호출은 동기식이며 페이지가 로드되거나 요소를 기다리는 동안 서버를 차단합니다. 단일 사용자 로컬 도구에는 문제없지만, 다중 클라이언트 서버라면 asyncio.to_thread를 통해 스레드 풀에서 실행하는 것이 좋습니다.

• Headless vs Headed. 기본은 headed(headless=False)이므로 브라우저가 작동하는 것을 볼 수 있고 headless Chrome을 차단하는 사이트도 작동합니다. 흐름이 확인된 후에는 백그라운드/서버 사용을 위해 headless=True를 전달하세요. sb_server.py의 uc=True(undetected- chromedriver)도 봇 탐지 벽에 대응하는 데 도움이 됩니다.

확장

도구를 추가하는 것은 해당 SeleniumBase 메서드를 호출하는 @mcp.tool() 데코레이터가 붙은 함수를 추가하는 것뿐입니다 — SeleniumBase에는 파일 업로드, 호버링, 알림, 네트워크 조건 등 위에서 아직 래핑하지 않은 메서드가 더 있습니다.

cdp_server.py — Pure CDP 모드

seleniumbase.sb_cdp.Chrome을 래핑합니다. SeleniumBase의 가장 은밀한 모드입니다: 브라우저는 Chrome DevTools Protocol로만 구동되며 WebDriver가 전혀 관여하지 않습니다. 참조: cdp_mode_methods.md.

도구 그룹

CDP 특정 설계 노트

• 요소는 핸들로 전달되지 않습니다. 네이티브 CDP 모드에서 find_element()는 자체 메서드(el.click(), el.get_html(), ...)를 가진 라이브 객체를 반환합니다. MCP 도구는 JSON 직렬화 가능한 데이터만 반환할 수 있으므로, find_element_info/find_all_info는 추가 메서드를 호출할 수 있는 핸들을 반환하는 대신 요소를 즉시 일반 dict(tag_name, text, html)로 변환합니다. 여러 일치 항목 중 하나에 대해 작업해야 하는 경우 "찾은 다음 클릭"을 두 단계로 나누는 대신 click_nth_element(위치 기준으로 작동)를 사용하세요.

• 캡차 해결은 보편적이지 않습니다. solve_captcha는 지원되는 챌린지 유형(예: SeleniumBase 데모 앱의 Cloudflare Turnstile)을 처리합니다. 임의의 CAPTCHA에 대한 보장된 우회는 아닙니다.

• 세션 종료. sb.quit()(close_browser에서 사용)은 세션을 종료하는 문서화된 방법입니다. 프로세스가 종료될 때 호출하지 않아도 브라우저는 자동으로 닫힙니다.

• 래핑되지 않음: PyAutoGUI 기반 gui_* 메서드(설계상 제외 — 최상위 설계 노트 참조), 저수준 내부 연결(get_websocket_url, add_handler, 권한 부여, 원시 get_document/get_flattened_document) 및 정확한 메서드 별칭(open/goto vs get)은 도구 목록을 집중적으로 유지하기 위해 제외되었습니다 — 필요하다면 다른 도구와 동일한 방식으로 추가하세요.

sb_server.py — with 문 없이 사용하는 SB()

일반적으로 컨텍스트 관리자로 사용되는 seleniumbase.SB()를 래핑합니다:

with SB(uc=True) as sb:
    sb.goto(...)

MCP 서버의 도구 호출은 별도의 함수 호출에서 한 번에 하나씩 발생합니다 — with를 감쌀 단일 들여쓰기 블록이 없으므로 — 이 서버는 대신 컨텍스트 관리자 프로토콜을 수동으로 호출합니다:

sb_context = SB(**kwargs)
sb = sb_context.__enter__()   # in start_browser
...
sb_context.__exit__(None, None, None)   # in close_browser

sb는 BaseCase 인스턴스로, SeleniumBase의 가장 광범위한 API입니다 — Driver(driver_server.py에 있음)가 노출하는 것의 상위 집합이며, UC 모드 스텔스 헬퍼와 driver_server.py/cdp_server.py에는 없는 몇 가지 추가 기능이 포함됩니다. 이 서버는 이미 다루어진 모든 것을 다시 래핑하는 대신 이러한 추가 기능에 초점을 맞춥니다:

또한 다른 두 서버와 동일한 핵심 탐색/상호작용/대기/어서션/쿠키/ 스크롤링/탭/출력 도구가 Driver나 CDP의 메서드 이름이 아닌 BaseCase 메서드 이름(예: sb.goto, sb.click, sb.assert_element)을 통해 호출됩니다.

SB() 관련 설계 노트

• UC 모드(스텔스 모드)는 시작 시 uc=True가 필요합니다. 필요할 경우 start_browser에서 미리 전달하세요.

• activate_cdp_mode는 새 세션을 시작하지 않습니다. 기존 sb 세션의 기본 모드를 후속 작업을 위해 Pure CDP로 전환합니다 — 새 브라우저가 아닌 흐름 중간의 확장입니다.