webdriverio/mcp

WebDriverIO를 사용하여 AI 어시스턴트가 웹 브라우저 및 모바일 애플리케이션과 상호작용할 수 있도록 지원하는 Model Context Protocol (MCP) 서버입니다. Chrome, Firefox, Edge, Safari 브라우저와 iOS 및 Android 앱을 통합된 인터페이스를 통해 자동화하세요.

다음 설정을 MCP 클라이언트 설정에 추가하세요:

표준 설정 (대부분의 클라이언트에서 작동):

{
"mcpServers": {
"wdio-mcp": {
...

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS),
%APPDATA%\Claude\claude_desktop_config.json (Windows), 또는 ~/.config/Claude/claude_desktop_config.json (Linux) 파일을 편집하세요:

{
"mcpServers": {
"wdio-mcp": {
...

Claude Code

claude mcp add wdio-mcp -- npx -y @wdio/mcp@latest

Cline

VS Code의 settings.json 또는 cline_mcp_settings.json 파일에 추가하세요:

{
"mcpServers": {
"wdio-mcp": {
...

Cursor

Cursor Settings
→ MCP
→ Add new MCP Server로 이동하거나, .cursor/mcp.json을 생성하세요:

{
"mcpServers": {
"wdio-mcp": {
...

Codex

Codex CLI를 사용하세요:

codex mcp add wdio-mcp npx "@wdio/mcp@latest"

또는 ~/.codex/config.toml을 편집하세요:

[mcp_servers.wdio-mcp]
command = "npx"
args = ["@wdio/mcp@latest"]

Goose

Advanced settings
→ Extensions
→ Add custom extension으로 이동하거나, 다음을 실행하세요:

goose configure

또는 ~/.config/goose/config.yaml을 편집하세요:

extensions:
wdio-mcp:
name: WebDriverIO MCP
...

Windsurf

~/.codeium/windsurf/mcp_config.json을 편집하세요:

{
"mcpServers": {
"wdio-mcp": {
...

Zed

Zed 설정(~/.config/zed/settings.json)을 편집하세요:

{
"context_servers": {
"wdio-mcp": {
...

VS Code (Copilot)

code --add-mcp '{"name":"wdio-mcp","command":"npx","args":["-y","@wdio/mcp@latest"]}'

⚠️ 재시작 필요: 설정을 추가한 후, 변경 사항을 적용하려면 MCP 클라이언트를 완전히 재시작해야 합니다.

전역(globally) 설치를 선호하는 경우:

npm install -g @wdio/mcp

그 다음 wdio-mcp를 명령어로 사용하세요:

{
"mcpServers": {
"wdio-mcp": {
...

📖 도움이 필요하신가요? MCP 설치 가이드를 따르세요.

기본적으로 서버는 stdio (subprocess) 전송 방식을 사용합니다. 서브프로세스 (subprocess)를 실행할 수 없는 클라이언트(예: llama.cpp, OpenAI Codex 보안 모드)의 경우, HTTP 전송 방식을 활성화하세요:

npx @wdio/mcp --http --port 3000

플래그 (Flag)	기본값 (Default)	설명 (Description)
--http	—	HTTP 전송 모드 활성화
--port	3000	리스닝(listen)할 포트
--allowedHosts	localhost,127.0.0.1,::1	허용된 Host 헤더 값 (DNS 리바인딩 보호)
--allowedOrigins	(없음 — 브라우저 클라이언트 차단됨)	CORS를 위한 허용된 Origin 값. 모두 허용하려면 *를 사용하세요.

그 다음 MCP 클라이언트가 http://localhost:3000/mcp를 가리키도록 설정하세요.

Appium Server: npm install -g appium 명령어로 전역 설치하세요.

플랫폼 드라이버 (Platform Drivers):

• iOS: appium driver install xcuitest (macOS에서 Xcode 필요)
• Android: appium driver install uiautomator2 (Android Studio 필요)

디바이스/에뮬레이터 (Devices/Emulators):

• iOS Simulator (macOS) 또는 실제 디바이스
• Android Emulator 또는 실제 디바이스

iOS 실제 디바이스의 경우: 디바이스의 UDID (Unique Device Identifier)가 필요합니다.
macOS에서 UDID 찾기: 디바이스 연결 → Finder 열기 → 디바이스 선택 → 디바이스 이름/모델을 클릭하여 UDID 확인
Windows에서 UDID 찾기: 디바이스 연결 → iTunes 또는 Apple Devices 앱 → 디바이스 아이콘 클릭 → "일련 번호(Serial Number)"를 클릭하여 UDID 확인
Xcode 방식: Window → Devices and Simulators → 디바이스 선택 → "Identifier"로 표시된 UDID 확인

모바일 기능을 사용하기 전에 Appium 서버를 시작하세요:

appium
# 서버는 기본적으로 http://127.0.0.1:4723 에서 실행됩니다

로컬 설정 없이 클라우드 실제 디바이스 및 브라우저에서 브라우저와 모바일 앱 테스트를 실행하세요. 현재 BrowserStack, Sauce Labs, LambdaTest, 그리고 TestingBot을 지원합니다.

제공업체(provider) 자격 증명을 환경 변수 또는 MCP 클라이언트 설정에 지정하세요:

BrowserStack

export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key

{
"mcpServers": {
"wdio-mcp": {
...

Sauce Labs

Sauce Labs

export SAUCE_USERNAME=your_username
export SAUCE_ACCESS_KEY=your_access_key

{
"mcpServers": {
"wdio-mcp": {
...

| SAUCE_USERNAME |
| Sauce Labs 사용자 이름 (필수) |
| SAUCE_ACCESS_KEY |
| Sauce Labs 액세스 키 (필수) |

데이터 센터는 start_session의 region 매개변리를 통해 세션별로 설정합니다 (기본값은 eu-central-1입니다).

LambdaTest (TestMu)

export TESTMU_USERNAME=your_username
export TESTMU_ACCESS_KEY=your_access_key

{
"mcpServers": {
"wdio-mcp": {
...

| TESTMU_USERNAME |
| LambdaTest 사용자 이름 (필수) |
| TESTMU_ACCESS_KEY |
| LambdaTest 액세스 키 (필수) |

TestingBot

export TESTINGBOT_KEY=your_key
export TESTINGBOT_SECRET=your_secret

{
"mcpServers": {
"wdio-mcp": {
...

| TESTINGBOT_KEY |
| TestingBot 키 (필수) |
| TESTINGBOT_SECRET |
| TestingBot 비밀 키 (필수) |

특정 OS/버전 조합에서 브라우저 실행:

// BrowserStack
start_session({
provider: 'browserstack',
...

Provider별 os/osVersion 동작 방식:

BrowserStack의 경우, os와 osVersion은 각각 별도의 bstack:options.os 및 bstack:options.osVersion 필드로 매핑됩니다. Sauce Labs / LambdaTest / TestingBot의 경우, os와 osVersion이 W3C platformName 기능으로 결합됩니다 (예: os: 'Windows' + osVersion: '11' → platformName: 'Windows 11'). 이 Provider들은 `

, 또는 noReset입니다.

이 Provider는 에뮬레이터에서 브라우저를 직접 실행합니다.

이전에 업로드된 앱을 확인하려면 list_apps를 사용하세요:

list_apps({ provider: 'browserstack' })
list_apps({ provider: 'saucelabs', sortBy: 'app_name' })
list_apps({ provider: 'testmu' })
...

로컬 머신이나 내부 네트워크에서만 접근 가능한 URL을 대상으로 테스트하려면, 로컬 터널 (local tunnel)을 활성화하세요:

// 터널 자동 시작 (Provider가 라이프사이클을 관리함)
start_session({
provider: 'saucelabs',
...

tunnel 파라미터는 지원 중단 예정(deprecated)인 browserstackLocal, saucelabsLocal, 그리고 testmuLocal 파라미터를 대체합니다. 터널을 자동으로 시작하려면(세션 종료 후 자동으로 중지됨) true로 설정하고, 머신에서 이미 실행 중인 터널을 사용하려면 'external'로 설정하세요.

참고: tunnel: true를 사용하면 Provider가 터널 바이너리 (binary)를 대신 다운로드하고 관리합니다. tunnel: 'external'의 경우 사용자가 직접 실행해야 합니다. wdio://saucelabs/local-binary, wdio://testmu/local-binary, 그리고 wdio://testingbot/local-binary 리소스를 통해 다운로드 URL과 설정 안내를 확인할 수 있습니다. TestingBot Tunnel은 플랫폼별 바이너리가 아닌, 단일 크로스 플랫폼 Java JAR (Java 11 이상 필요) 형태입니다.

모든 세션 유형은 Provider 대시보드에 표시되는 reporting 라벨을 지원합니다:

필드	설명
reporting.project	프로젝트 이름 아래에 세션 그룹화
reporting.build	빌드/버전 라벨로 세션 태그 지정
reporting.session	개별 테스트 세션의 이름

도구	설명
upload_app	로컬 .apk 또는 .ipa를 Provider에 업로드하며, 앱 URL/참조를 반환함
list_apps	Provider의 앱 스토리지에 이전에 업로드된 앱 목록을 나열함

두 도구 모두 provider 파라미터 ('browserstack', 'saucelabs', 'testmu', 또는 'testingbot')가 필요합니다.

세션 관리 (Session Management): 브라우저 세션(Chrome, Firefox, Edge, Safari)을 헤드리스 (headless) 또는 헤디드 (headed) 모드로 시작 및 종료
탐색 및 상호작용 (Navigation & Interaction): URL 탐색, 요소 클릭, 양식 작성 및 콘텐츠 가져오기
페이지 분석 (Page Analysis): 가시적 요소, 접근성 트리 (accessibility trees) 가져오기, 스크린샷 촬영
쿠키 관리 (Cookie Management): 쿠키 가져오기, 설정 및 삭제
스크롤링 (Scrolling): 설정 가능한 거리로 부드러운 스크롤링 수행
실행 중인 Chrome에 연결 (Attach to running Chrome): --remote-debugging-port를 통해 기존 Chrome 창에 연결

— 인증되었거나 사전 구성된 세션을 테스트하기에 이상적임
기기 에뮬레이션 (Device emulation): 물리적 기기 없이 반응형 레이아웃을 시뮬레이션하기 위해 모바일/태블릿 프리셋(iPhone 15, Pixel 7 등) 적용
세션 녹화 (Session Recording): 모든 도구 호출(tool calls)은 자동으로 기록되며 실행 가능한 WebdriverIO JS로 내보낼 수 있음

네이티브 앱 테스트 (Native App Testing): Appium을 통해 iOS (.app/.ipa) 및 Android (.apk) 앱 테스트
터치 제스처 (Touch Gestures): 탭 (tap), 스와이프 (swipe), 롱 프레스 (long-press), 드래그 앤 드롭 (drag-and-drop)
앱 생명주기 (App Lifecycle): 앱 실행, 백그라운드 전환, 종료, 앱 상태 확인
컨텍스트 전환 (Context Switching): 하이브리드 앱을 위해 네이티브와 웹뷰 (webview) 컨텍스트 간 원활한 전환
기기 제어 (Device Control): 회전, 잠금/해제, 지리 위치 (geolocation), 키보드 제어, 알림
크로스 플랫폼 셀렉터 (Cross-Platform Selectors): Accessibility IDs, XPath, UiAutomator (Android), Predicates (iOS)

도구 (Tool)	설명
start_session	브라우저 또는 앱 세션을 시작합니다. 웹의 경우 platform: 'browser', 모바일의 경우 platform: 'ios' / 'android'를 사용하거나, 실행 중인 Chrome 인스턴스에 연결하려면 attach: true를 사용합니다
launch_chrome	원격 디버깅이 활성화된 새 Chrome 인스턴스를 실행합니다 (start_session({ attach: true })와 함께 사용)
close_session	현재 세션을 종료하거나 분리합니다 (detach: true를 사용하여 종료하지 않고 연결을 해제하는 것을 지원)
emulate_device	모바일/태블릿 기기 프리셋(viewport, DPR, UA, touch)을 에뮬레이션합니다. BiDi 세션이 필요합니다

도구 (Tool)	설명 (Description)
navigate	URL로 이동합니다
get_elements	페이지 내에서 보이는 상호작용 가능한 요소들을 가져옵니다. 뷰포트(viewport) 요소만 필터링하는 inViewportOnly (기본값: true)와 모바일에서 레이아웃 컨테이너를 포함하는 includeContainers (기본값: false)를 지원합니다
get_accessibility_tree	역할(role), 이름(name), 선택자(selector)가 포함된 페이지 접근성 트리(accessibility tree)를 가져옵니다. 역할(role)에 따른 필터링과 페이지네이션(pagination)을 지원합니다. 브라우저 전용 (Browser-only)
get_screenshot	현재 페이지 또는 화면의 스크린샷을 찍습니다 (base64 인코딩, 최대 2000px / 1MB로 자동 크기 조정)
get_tabs	핸들(handle), 제목, URL 및 활성 상태와 함께 열려 있는 모든 브라우저 탭을 나열합니다. 브라우저 전용 (Browser-only)
scroll	지정된 픽셀만큼 특정 방향(위/아래)으로 스크롤합니다. 브라우저 전용 (Browser-only)
execute_script	브라우저에서 임의의 JavaScript를 실행하거나, 기기에서 Appium 모바일 명령을 실행합니다
switch_tab	핸들 또는 0부터 시작하는 인덱스를 사용하여 다른 브라우저 탭으로 전환합니다. 브라우저 전용 (Browser-only)
switch_frame	CSS/XPath 선택자를 통해 iframe으로 전환하거나, 선택자가 주어지지 않으면 최상위 프레임(top-level frame)으로 돌아갑니다. 브라우저 전용 (Browser-only)

도구 (Tool)	설명 (Description)
click_element	요소를 클릭합니다
set_value	입력 필드에 텍스트를 입력합니다

도구 (Tool)	설명 (Description)
get_cookies	현재 세션의 모든 쿠키를 가져오거나, 이름으로 특정 쿠키 하나를 가져옵니다
set_cookie	이름, 값 및 선택적 속성을 사용하여 쿠키를 설정합니다
delete_cookies	모든 쿠키를 삭제하거나 특정 쿠키를 삭제합니다

도구 (Tool)	설명 (Description)
tap_element	선택자 또는 좌표를 사용하여 요소를 탭(tap)합니다
swipe	특정 방향(위/아래/왼쪽/오른쪽)으로 스와이프(swipe)합니다
drag_and_drop	한 위치에서 다른 위치로 드래그 앤 드롭(drag and drop)합니다

도구 (Tool)	설명 (Description)
get_contexts	사용 가능한 자동화 컨텍스트(NATIVE_APP, WEBVIEW_*)와 현재 활성화된 컨텍스트를 나열합니다
switch_context	네이티브(native) 컨텍스트와 웹뷰(webview) 컨텍스트 간에 전환합니다

도구 (Tool)	설명 (Description)
get_app_state	모바일 앱의 현재 라이프사이클 상태를 가져옵니다 (설치되지 않음 / 실행 중이지 않음 / 백그라운드 / 포그라운드)
rotate_device	세로(portrait) 또는 가로(landscape) 모드로 회전합니다
hide_keyboard	화면의 키보드를 숨깁니다
set_geolocation	기기의 GPS 위치를 설정합니다