WebDriverIO

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with web browsers and mobile applications using WebDriverIO. Automate Chrome browsers, iOS apps, and Android apps—all through a unified interface.

- Native App Testing: Test iOS (.app/.ipa) and Android (.apk) apps via Appium
- Touch Gestures: Tap, swipe, long-press, drag-and-drop
- App Lifecycle: Launch, background, terminate, check app state
- Context Switching: Seamlessly switch between native and webview contexts for hybrid apps
- Device Control: Rotate, lock/unlock, geolocation, keyboard control, notifications
- Cross-Platform Selectors: Accessibility IDs, XPath, UiAutomator (Android), Predicates (iOS)

Navigation & Page Interaction (Web & Mobile)

- Node.js (version 18 or higher)
- Claude Desktop application
- Chrome browser (automatically managed by WebDriverIO)

- Appium Server: Install globally withnpm install -g appium
- Platform Drivers:

- iOS:appium driver install xcuitest(requires Xcode on macOS)
- Android:appium driver install uiautomator2(requires Android Studio)

- iOS Simulator (macOS) or physical device
- Android Emulator or physical device

- Find UDID on macOS: Connect device → Open Finder → Select device → Click device name/model to reveal UDID
- Find UDID on Windows: Connect device → iTunes or Apple Devices app → Click device icon → Click "Serial Number" to reveal UDID
- Xcode method: Window → Devices and Simulators → Select device → UDID shown as "Identifier"
-

Configure Claude Desktop:Add the following configuration to your Claude Desktop MCP settings:

Restart Claude Desktop:⚠️Important:You may need to fully restart Claude Desktop. On Windows, use Task Manager to ensure it's completely closed before restarting.

For Mobile Automation (Optional):Start the Appium server before using mobile features:

appium # Server runs at http://127.0.0.1:4723 by default

Example 1: Testing Demo Android App (Book Scanning)

Test the Demo Android app at C:\Users\demo-liveApiGbRegionNonMinifiedRelease-3018788.apk on emulator-5554: 1. Start the app with auto-grant permissions 2. Get visible elements on the onboarding screen 3. Tap "Skip" to bypass onboarding 4. Verify main screen loads 5. Take a screenshot

Example 2: Testing World of Books E-commerce Site

// Default settings (headed mode, 1280x1080) start_browser() // Headless mode start_browser({ headless: true }) // Custom dimensions start_browser({ windowWidth: 1920, windowHeight: 1080 }) // Headless with custom dimensions start_browser({ headless: true, windowWidth: 1920, windowHeight: 1080 })

Test my iOS app located at /path/to/MyApp.app on iPhone 15 Pro simulator: 1. Start the app session 2. Tap the login button 3. Enter "testuser" in the username field 4. Take a screenshot of the home screen 5. Close the session

Test my Android app without resetting data: 1. Start app session with noReset: true and fullReset: false 2. App launches with existing login state and user data preserved 3. Run test scenarios 4. Close session (app remains installed with data intact)

Test my iOS app on my physical iPhone: 1. Start app session with: - platform: iOS - appPath: /path/to/MyApp.ipa - deviceName: My iPhone - udid: 00008030-001234567890ABCD (your device's UDID) - platformVersion: 17.0 2. Run your test scenario 3. Close the session

Test my Android app /path/to/app.apk on the Pixel_6_API_34 emulator: 1. Start the app with auto-grant permissions 2. Get visible elements (use inViewportOnly: false to see all elements) 3. Swipe up to scroll 4. Tap on the "Settings" button using text matching 5. Verify the settings screen is displayed

Test my app and debug layout issues: 1. Start the app session 2. Get visible elements with includeContainers: true to see the layout hierarchy 3. Analyze ViewGroup, FrameLayout, and ScrollView containers 4. Use inViewportOnly: false to find off-screen elements that need scrolling

Hybrid app testing (switching contexts):

Test my hybrid app: 1. Start the Android app session 2. Tap "Open Web" button in native context 3. List available contexts 4. Switch to WEBVIEW context 5. Click the login button using CSS selector 6. Switch back to NATIVE_APP context 7. Verify we're back on the home screen

- Only one session (browser OR app) can be active at a time
- Always close sessions when done to free system resources
- To switch between browser and mobile, close the current session first
- Useclose_session({ detach: true })to disconnect without terminating the session on the Appium server
- State preservationcan be controlled withnoResetandfullResetparameters during session creation
- Sessions created withnoReset: trueor withoutappPathwill automatically detach on close

- Break complex automation into smaller, focused operations
- Claude may consume message limits quickly with extensive automation

- Appium server must be running before starting mobile sessions
- Ensure emulators/simulators are running and devices are connected
- iOS automation requires macOS with Xcode installed
- iOS Real Devices: Testing on physical iOS devices requires the device's UDID (40-character unique identifier). See Prerequisites section for how to find your UDID