{"id":40448657,"url":"https://github.com/webdriverio/mcp","last_synced_at":"2026-04-09T16:21:29.038Z","repository":{"id":330430249,"uuid":"1122210039","full_name":"webdriverio/mcp","owner":"webdriverio","description":"A Model Context Protocol (MCP) server that enables AI assistants to interact with web browsers and mobile applications using WebDriverIO. Automate Chrome browsers, iOS apps, and Android apps—all through a unified interface.","archived":false,"fork":false,"pushed_at":"2026-04-02T01:18:01.000Z","size":832,"stargazers_count":22,"open_issues_count":6,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T04:58:56.140Z","etag":null,"topics":["android","appium","browser","ios","mcp","mobile","testing","webdriverio"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@wdio/mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webdriverio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"tidelift":"npm/webdriverio","open_collective":"webdriverio"}},"created_at":"2025-12-24T09:35:16.000Z","updated_at":"2026-04-01T15:43:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/webdriverio/mcp","commit_stats":null,"previous_names":["webdriverio/mcp"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/webdriverio/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webdriverio","download_url":"https://codeload.github.com/webdriverio/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31489427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","appium","browser","ios","mcp","mobile","testing","webdriverio"],"created_at":"2026-01-20T17:09:39.743Z","updated_at":"2026-04-06T21:02:46.802Z","avatar_url":"https://github.com/webdriverio.png","language":"TypeScript","funding_links":["https://tidelift.com/funding/github/npm/webdriverio","https://opencollective.com/webdriverio"],"categories":[],"sub_categories":[],"readme":"# WebDriverIO MCP Server\n\nA Model Context Protocol (MCP) server that enables AI assistants to interact with web browsers and mobile applications\nusing WebDriverIO. Automate Chrome, Firefox, Edge, and Safari browsers plus iOS and Android apps—all through a unified interface.\n\n## Installation\n\n[![mcp MCP server](https://glama.ai/mcp/servers/webdriverio/mcp/badges/score.svg)](https://glama.ai/mcp/servers/webdriverio/mcp)\n\nAdd the following configuration to your MCP client settings:\n\n**Standard config** (works in most clients):\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"]\n    }\n  }\n}\n```\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install%20Server-0098FF?style=flat-square)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522wdio-mcp%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540wdio%252Fmcp%2540latest%2522%255D%257D)\n[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install%20Server-24bfa5?style=flat-square)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522wdio-mcp%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540wdio%252Fmcp%2540latest%2522%255D%257D)\n[\u003cimg src=\"https://cursor.com/deeplink/mcp-install-dark.svg\" alt=\"Install in Cursor\"\u003e](https://cursor.com/en/install-mcp?name=WebDriverIO\u0026config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3ZGlvL21jcEBsYXRlc3QiXX0%3D)\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Desktop\u003c/summary\u003e\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows), or `~/.config/Claude/claude_desktop_config.json` (Linux):\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eClaude Code\u003c/summary\u003e\n\n```bash\nclaude mcp add wdio-mcp -- npx -y @wdio/mcp@latest\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCline\u003c/summary\u003e\n\nAdd to your VS Code `settings.json` or `cline_mcp_settings.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCursor\u003c/summary\u003e\n\nGo to `Cursor Settings` → `MCP` → `Add new MCP Server`, or create `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCodex\u003c/summary\u003e\n\nUse the Codex CLI:\n\n```bash\ncodex mcp add wdio-mcp npx \"@wdio/mcp@latest\"\n```\n\nOr edit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.wdio-mcp]\ncommand = \"npx\"\nargs = [\"@wdio/mcp@latest\"]\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGoose\u003c/summary\u003e\n\nGo to `Advanced settings` → `Extensions` → `Add custom extension`, or run:\n\n```bash\ngoose configure\n```\n\nOr edit `~/.config/goose/config.yaml`:\n\n```yaml\nextensions:\n  wdio-mcp:\n    name: WebDriverIO MCP\n    cmd: npx\n    args: [-y, \"@wdio/mcp@latest\"]\n    enabled: true\n    type: stdio\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWindsurf\u003c/summary\u003e\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eZed\u003c/summary\u003e\n\nEdit Zed settings (`~/.config/zed/settings.json`):\n\n```json\n{\n  \"context_servers\": {\n    \"wdio-mcp\": {\n      \"source\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eVS Code (Copilot)\u003c/summary\u003e\n\n```bash\ncode --add-mcp '{\"name\":\"wdio-mcp\",\"command\":\"npx\",\"args\":[\"-y\",\"@wdio/mcp@latest\"]}'\n```\n\u003c/details\u003e\n\n----\n\u003e ⚠️ **Restart Required**: After adding the configuration, fully restart your MCP client to apply the changes.\n\n### Option 2: Global Installation\n\nIf you prefer to install globally:\n\n```bash\nnpm install -g @wdio/mcp\n```\n\nThen use `wdio-mcp` as the command:\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"command\": \"wdio-mcp\"\n    }\n  }\n}\n```\n\n📖 **Need help?** Follow the [MCP install guide](https://modelcontextprotocol.io/quickstart/user).\n\n### Prerequisites For Mobile App Automation\n\n- **Appium Server**: Install globally with `npm install -g appium`\n- **Platform Drivers**:\n    - iOS: `appium driver install xcuitest` (requires Xcode on macOS)\n    - Android: `appium driver install uiautomator2` (requires Android Studio)\n- **Devices/Emulators**:\n    - iOS Simulator (macOS) or physical device\n    - Android Emulator or physical device\n- **For iOS Real Devices**: You'll need the device's UDID (Unique Device Identifier)\n    - **Find UDID on macOS**: Connect device → Open Finder → Select device → Click device name/model to reveal UDID\n    - **Find UDID on Windows**: Connect device → iTunes or Apple Devices app → Click device icon → Click \"Serial Number\"\n      to reveal UDID\n    - **Xcode method**: Window → Devices and Simulators → Select device → UDID shown as \"Identifier\"\n\nStart the Appium server before using mobile features:\n\n```bash\nappium\n# Server runs at http://127.0.0.1:4723 by default\n```\n\n## BrowserStack\n\nRun browser and mobile app tests on [BrowserStack](https://www.browserstack.com/) real devices and browsers without any local setup.\n\n### Prerequisites\n\nSet your credentials as environment variables:\n\n```bash\nexport BROWSERSTACK_USERNAME=your_username\nexport BROWSERSTACK_ACCESS_KEY=your_access_key\n```\n\nOr add them to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"wdio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wdio/mcp@latest\"],\n      \"env\": {\n        \"BROWSERSTACK_USERNAME\": \"your_username\",\n        \"BROWSERSTACK_ACCESS_KEY\": \"your_access_key\"\n      }\n    }\n  }\n}\n```\n\n### Browser Sessions\n\nRun a browser on a specific OS/version combination:\n\n```javascript\nstart_session({\n  provider: 'browserstack',\n  platform: 'browser',\n  browser: 'chrome',           // chrome | firefox | edge | safari\n  browserVersion: 'latest',    // default: latest\n  os: 'Windows',               // e.g. \"Windows\", \"OS X\"\n  osVersion: '11',             // e.g. \"11\", \"Sequoia\"\n  reporting: {\n    project: 'My Project',\n    build: 'v1.2.0',\n    session: 'Login flow'\n  }\n})\n```\n\n### Mobile App Sessions\n\nTest on BrowserStack real devices. First upload your app (or use an existing `bs://` URL):\n\n```javascript\n// Upload a local .apk or .ipa (returns a bs:// URL)\nupload_app({ path: '/path/to/app.apk' })\n\n// Start a session with the returned URL\nstart_session({\n  provider: 'browserstack',\n  platform: 'android',         // android | ios\n  app: 'bs://abc123...',       // bs:// URL or custom_id from upload\n  deviceName: 'Samsung Galaxy S23',\n  platformVersion: '13.0',\n  reporting: {\n    project: 'My Project',\n    build: 'v1.2.0',\n    session: 'Checkout flow'\n  }\n})\n```\n\nUse `list_apps` to see previously uploaded apps:\n\n```javascript\nlist_apps()                               // own uploads, sorted by date\nlist_apps({ sortBy: 'app_name' })\nlist_apps({ organizationWide: true })     // all uploads in your org\n```\n\n### BrowserStack Local\n\nTo test against URLs that are only accessible on your local machine or internal network, enable the BrowserStack Local tunnel:\n\n```javascript\nstart_session({\n  provider: 'browserstack',\n  platform: 'browser',\n  browser: 'chrome',\n  browserstackLocal: true      // starts tunnel automatically\n})\n```\n\n### Reporting Labels\n\nAll session types support `reporting` labels that appear in the BrowserStack Automate dashboard:\n\n| Field                     | Description                                |\n|---------------------------|--------------------------------------------|\n| `reporting.project`       | Group sessions under a project name        |\n| `reporting.build`         | Tag sessions with a build/version label    |\n| `reporting.session`       | Name for the individual test session       |\n\n### BrowserStack Tools\n\n| Tool          | Description                                                                      |\n|---------------|----------------------------------------------------------------------------------|\n| `upload_app`  | Upload a local `.apk` or `.ipa` to BrowserStack; returns a `bs://` URL          |\n| `list_apps`   | List apps previously uploaded to your BrowserStack account                       |\n\n## Features\n\n### Browser Automation\n\n- **Session Management**: Start and close browser sessions (Chrome, Firefox, Edge, Safari) with headless/headed modes\n- **Navigation \u0026 Interaction**: Navigate URLs, click elements, fill forms, and retrieve content\n- **Page Analysis**: Get visible elements, accessibility trees, take screenshots\n- **Cookie Management**: Get, set, and delete cookies\n- **Scrolling**: Smooth scrolling with configurable distances\n- **Attach to running Chrome**: Connect to an existing Chrome window via `--remote-debugging-port` — ideal for testing authenticated or pre-configured sessions\n- **Device emulation**: Apply mobile/tablet presets (iPhone 15, Pixel 7, etc.) to simulate responsive layouts without a physical device\n- **Session Recording**: All tool calls are automatically recorded and exportable as runnable WebdriverIO JS\n\n### Mobile App Automation (iOS/Android)\n\n- **Native App Testing**: Test iOS (.app/.ipa) and Android (.apk) apps via Appium\n- **Touch Gestures**: Tap, swipe, long-press, drag-and-drop\n- **App Lifecycle**: Launch, background, terminate, check app state\n- **Context Switching**: Seamlessly switch between native and webview contexts for hybrid apps\n- **Device Control**: Rotate, lock/unlock, geolocation, keyboard control, notifications\n- **Cross-Platform Selectors**: Accessibility IDs, XPath, UiAutomator (Android), Predicates (iOS)\n\n## Available Tools\n\n### Session Management\n\n| Tool             | Description                                                                              |\n|------------------|------------------------------------------------------------------------------------------|\n| `start_session`  | Start a browser or app session. Use `platform: 'browser'` for web, `platform: 'ios'`/`'android'` for mobile, or `attach: true` to connect to a running Chrome instance |\n| `launch_chrome`  | Launch a new Chrome instance with remote debugging enabled (for use with `start_session({ attach: true })`) |\n| `close_session`  | Close or detach from the current session (supports `detach: true` to disconnect without terminating) |\n| `emulate_device` | Emulate a mobile/tablet device preset (viewport, DPR, UA, touch); requires BiDi session |\n\n### Navigation \u0026 Page Interaction (Web \u0026 Mobile)\n\n| Tool            | Description                                                                                                                                                                                         |\n|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `navigate`      | Navigate to a URL                                                                                                                                                                                   |\n| `get_elements`  | Get visible, interactable elements on the page. Supports `inViewportOnly` (default: true) to filter viewport elements, and `includeContainers` (default: false) to include layout containers on mobile |\n| `scroll`        | Scroll in a direction (up/down) by specified pixels                                                                                                                                                 |\n| `execute_script` | Execute arbitrary JavaScript in the browser context                                                                                                                                                |\n| `switch_tab`    | Switch to a different browser tab by index or URL                                                                                                                                                   |\n\n### Element Interaction (Web \u0026 Mobile)\n\n| Tool            | Description                 |\n|-----------------|-----------------------------|\n| `click_element` | Click an element            |\n| `set_value`     | Type text into input fields |\n\n### Cookie Management (Web)\n\n| Tool             | Description                                            |\n|------------------|--------------------------------------------------------|\n| `set_cookie`     | Set a cookie with name, value, and optional attributes |\n| `delete_cookies` | Delete all cookies or a specific cookie                |\n\n### Mobile Gestures (iOS/Android)\n\n| Tool            | Description                               |\n|-----------------|-------------------------------------------|\n| `tap_element`   | Tap an element by selector or coordinates |\n| `swipe`         | Swipe in a direction (up/down/left/right) |\n| `drag_and_drop` | Drag from one location to another         |\n\n### Context Switching (Hybrid Apps)\n\n| Tool             | Description                                     |\n|------------------|-------------------------------------------------|\n| `switch_context` | Switch between native and webview contexts      |\n\n### Device Control (iOS/Android)\n\n| Tool              | Description                     |\n|-------------------|---------------------------------|\n| `rotate_device`   | Rotate to portrait or landscape |\n| `hide_keyboard`   | Hide on-screen keyboard         |\n| `set_geolocation` | Set device GPS location         |\n\n### MCP Resources (read-only, no tool call needed)\n\n| Resource                                  | Description                                            |\n|-------------------------------------------|--------------------------------------------------------|\n| `wdio://sessions`                         | Index of all recorded sessions                         |\n| `wdio://session/current/steps`            | Step log for the active session                        |\n| `wdio://session/current/code`             | Generated runnable WebdriverIO JS for the active session |\n| `wdio://session/{id}/steps`               | Step log for any past session by ID                    |\n| `wdio://session/{id}/code`                | Generated JS for any past session by ID                |\n| `wdio://session/current/elements`         | Interactable elements (viewport-only by default)       |\n| `wdio://session/current/accessibility`    | Accessibility tree                                     |\n| `wdio://session/current/screenshot`       | Screenshot (base64)                                    |\n| `wdio://session/current/cookies`          | Browser cookies                                        |\n| `wdio://session/current/tabs`             | Open browser tabs                                      |\n| `wdio://session/current/contexts`         | Native/webview contexts (mobile)                       |\n| `wdio://session/current/context`          | Currently active context (mobile)                      |\n| `wdio://session/current/app-state`        | Mobile app state                                       |\n| `wdio://session/current/geolocation`      | Device geolocation                                     |\n| `wdio://session/current/capabilities`     | Resolved WebDriver capabilities for the active session |\n| `wdio://browserstack/local-binary`        | BrowserStack Local binary download URL and start command |\n\n## Usage Examples\n\n### Real-World Test Cases\n\n**Example 1: Testing Demo Android App (Book Scanning)**\n\n```\nTest the Demo Android app at C:\\Users\\demo-liveApiGbRegionNonMinifiedRelease-3018788.apk on emulator-5554:\n1. Start the app with auto-grant permissions\n2. Get visible elements on the onboarding screen\n3. Tap \"Skip\" to bypass onboarding\n4. Verify main screen loads\n5. Take a screenshot\n```\n\n**Example 2: Testing World of Books E-commerce Site**\n\n```\nYou are a Testing expert, and want to assess the basic workflows of worldofbooks.com:\n- Open World of Books (accept all cookies)\n- Get visible elements to see navigation structure\n- Search for a fiction book\n- Choose one and validate if there are NEW and used book options\n- Report your findings at the end\n```\n\n### Browser Automation\n\n**Basic web testing prompt:**\n\n```\nYou are a Testing expert, and want to assess the basic workflows of a web application:\n- Open World of Books (accept all cookies)\n- Search for a fiction book\n- Choose one and validate if there are NEW and used book options\n- Report your findings at the end\n```\n\n**Browser configuration options:**\n\n```javascript\n// Default settings (headed mode, 1280x1080)\nstart_session({platform: 'browser'})\n\n// Firefox\nstart_session({platform: 'browser', browser: 'firefox'})\n\n// Edge\nstart_session({platform: 'browser', browser: 'edge'})\n\n// Safari (headed only; requires macOS)\nstart_session({platform: 'browser', browser: 'safari'})\n\n// Headless mode\nstart_session({platform: 'browser', headless: true})\n\n// Custom dimensions\nstart_session({platform: 'browser', windowWidth: 1920, windowHeight: 1080})\n\n// Pass custom capabilities (e.g. Chrome extensions, profile, prefs)\nstart_session({\n  platform: 'browser',\n  headless: false,\n  capabilities: {\n    'goog:chromeOptions': {\n      args: ['--user-data-dir=/tmp/wdio-mcp-profile', '--load-extension=/path/to/unpacked-extension']\n    }\n  }\n})\n```\n\n**Attach to a running Chrome instance:**\n\n```\n// First, launch Chrome with remote debugging enabled:\n//\n//   macOS (must quit Chrome first — open -a ignores args if Chrome is already running):\n//     pkill -x \"Google Chrome\" \u0026\u0026 sleep 1\n//     /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome \\\n//       --remote-debugging-port=9222 \\\n//       --user-data-dir=/tmp/chrome-debug \u0026\n//\n//   Linux:\n//     google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug \u0026\n//\n//   Verify it's ready: curl http://localhost:9222/json/version\nstart_session({attach: true})\nstart_session({attach: true, port: 9333})\nstart_session({attach: true, port: 9222, navigationUrl: 'https://app.example.com'})\n```\n\n**Device emulation (requires BiDi session):**\n\n```\n// Device emulation (requires BiDi session)\nstart_browser({capabilities: {webSocketUrl: true}})\nemulate_device()                         // list available presets\nemulate_device({device: 'iPhone 15'})    // activate emulation\nemulate_device({device: 'Pixel 7'})      // switch device\nemulate_device({device: 'reset'})        // restore desktop defaults\n```\n\n### Mobile App Automation\n\n**Testing an iOS app on simulator:**\n\n```\nTest my iOS app located at /path/to/MyApp.app on iPhone 15 Pro simulator:\n1. Start the app session\n2. Tap the login button\n3. Enter \"testuser\" in the username field\n4. Take a screenshot of the home screen\n5. Close the session\n```\n\n**Preserving app state between sessions:**\n\n```\nTest my Android app without resetting data:\n1. Start app session with noReset: true and fullReset: false\n2. App launches with existing login state and user data preserved\n3. Run test scenarios\n4. Close session (app remains installed with data intact)\n```\n\n**Testing an iOS app on real device:**\n\n```\nTest my iOS app on my physical iPhone:\n1. Start app session with:\n   - platform: iOS\n   - appPath: /path/to/MyApp.ipa\n   - deviceName: My iPhone\n   - udid: 00008030-001234567890ABCD (your device's UDID)\n   - platformVersion: 17.0\n2. Run your test scenario\n3. Close the session\n```\n\n**Testing an Android app:**\n\n```\nTest my Android app /path/to/app.apk on the Pixel_6_API_34 emulator:\n1. Start the app with auto-grant permissions\n2. Get visible elements (use inViewportOnly: false to see all elements)\n3. Swipe up to scroll\n4. Tap on the \"Settings\" button using text matching\n5. Verify the settings screen is displayed\n```\n\n**Advanced element detection:**\n\n```\nTest my app and debug layout issues:\n1. Start the app session\n2. Get visible elements with includeContainers: true to see the layout hierarchy\n3. Analyze ViewGroup, FrameLayout, and ScrollView containers\n4. Use inViewportOnly: false to find off-screen elements that need scrolling\n```\n\n**Hybrid app testing (switching contexts):**\n\n```\nTest my hybrid app:\n1. Start the Android app session\n2. Tap \"Open Web\" button in native context\n3. List available contexts\n4. Switch to WEBVIEW context\n5. Click the login button using CSS selector\n6. Switch back to NATIVE_APP context\n7. Verify we're back on the home screen\n```\n\n## Important Notes\n\n⚠️ **Session Management:**\n\n- Only one session (browser OR app) can be active at a time\n- Always close sessions when done to free system resources\n- To switch between browser and mobile, close the current session first\n- Use `close_session({ detach: true })` to disconnect without terminating the session on the Appium server\n- **State preservation** can be controlled with `noReset` and `fullReset` parameters during session creation\n- Sessions created with `noReset: true` or without `appPath` will automatically detach on close\n\n⚠️ **Task Planning:**\n\n- Break complex automation into smaller, focused operations\n- Claude may consume message limits quickly with extensive automation\n\n⚠️ **Mobile Automation:**\n\n- Appium server must be running before starting mobile sessions\n- Ensure emulators/simulators are running and devices are connected\n- iOS automation requires macOS with Xcode installed\n- **iOS Real Devices**: Testing on physical iOS devices requires the device's UDID (40-character unique identifier). See\n  Prerequisites section for how to find your UDID\n\n## Selector Syntax Quick Reference\n\n**Web (CSS/XPath):**\n\n- CSS: `button.my-class`, `#element-id`\n- XPath: `//button[@class='my-class']`\n- Text: `button=Exact text`, `a*=Contains text`\n\n**Mobile (Cross-Platform):**\n\n- Accessibility ID: `~loginButton` (works on both iOS and Android)\n- Android UiAutomator: `android=new UiSelector().text(\"Login\")`\n- iOS Predicate: `-ios predicate string:label == \"Login\" AND visible == 1`\n- XPath: `//android.widget.Button[@text=\"Login\"]`\n\n## Advanced Features\n\n### App State Preservation\n\n**State Preservation with noReset/fullReset:**\nControl app state when creating new sessions using the `noReset` and `fullReset` parameters:\n\n| noReset | fullReset | Behavior                                              |\n|---------|-----------|-------------------------------------------------------|\n| `true`  | `false`   | Preserve state: App stays installed, data preserved   |\n| `false` | `false`   | Clear app data but keep app installed (default)       |\n| `false` | `true`    | Full reset: Uninstall and reinstall app (clean slate) |\n\n**Example with state preservation:**\n\n```javascript\n// Preserve login state between test runs\nstart_session({\n    platform: 'android',\n    appPath: '/path/to/app.apk',\n    deviceName: 'emulator-5554',\n    noReset: true,         // Don't reset app state\n    fullReset: false,      // Don't uninstall\n    autoGrantPermissions: true,\n    capabilities: {\n        'appium:chromedriverExecutable': '/path/to/chromedriver',\n        'appium:autoWebview': true\n    }\n})\n// App launches with existing user data, login tokens, preferences intact\n```\n\n**Detach from Sessions:**\nThe `close_session` tool supports a `detach` parameter that disconnects from the session without terminating it on the\nAppium server:\n\n```javascript\n// Detach without killing the session\nclose_session({detach: true})\n\n// Standard session termination (closes the app and removes session)\nclose_session({detach: false})  // or just close_session()\n```\n\nSessions created with `noReset: true` or without `appPath` will automatically detach on close.\n\nThis is particularly useful when:\n\n* Preserving app state for manual testing continuation\n* Debugging multi-step workflows (leave session running between tool invocations)\n* Testing scenarios where you want the app to remain installed and in current state\n\n### Smart Element Detection\n\n- **Platform-specific element classification**: Automatically identifies interactable elements vs layout containers\n    - Android: Button, EditText, CheckBox vs ViewGroup, FrameLayout, ScrollView\n    - iOS: Button, TextField, Switch vs View, StackView, CollectionView\n- **Multiple locator strategies**: Each element provides accessibility ID, resource ID, text, XPath, and\n  platform-specific selectors\n- **Viewport filtering**: Control whether to get only visible elements or all elements including off-screen\n- **Layout debugging**: Optionally include container elements to understand UI hierarchy\n\n### Automatic Permission \u0026 Alert Handling\n\nBoth iOS and Android sessions now support automatic handling of system permissions and alerts:\n\n- `autoGrantPermissions` (default: true): Automatically grants app permissions (camera, location, etc.)\n- `autoAcceptAlerts` (default: true): Automatically accepts system alerts and dialogs\n- `autoDismissAlerts` (optional): Set to true to dismiss alerts instead of accepting them\n\nThis eliminates the need to manually handle permission popups during automated testing.\n\n## Technical Details\n\n- **Built with:** TypeScript, WebDriverIO, Appium\n- **Browser Support:** Chrome, Firefox, Edge (headed/headless, automated driver management), Safari (headed only; macOS)\n- **Mobile Support:** iOS (XCUITest) and Android (UiAutomator2/Espresso)\n- **Protocol:** Model Context Protocol (MCP) for Claude Desktop integration\n- **Session Model:** Single active session (browser or mobile app)\n- **Data Format:** TOON (Token-Oriented Object Notation) for efficient LLM communication\n- **Element Detection:** XML-based page source parsing with intelligent filtering and multi-strategy locator generation\n\n### Session Recording \u0026 Code Export\n\nEvery tool call is automatically recorded to a session history. You can inspect sessions and export runnable code via MCP resources — no extra tool calls needed:\n\n- `wdio://sessions` — lists all recorded sessions with type, timestamps, and step count\n- `wdio://session/current/steps` — step log for the active session\n- `wdio://session/current/code` — generated runnable WebdriverIO JS for the active session\n- `wdio://session/{sessionId}/steps` — step log for any past session by ID\n- `wdio://session/{sessionId}/code` — generated JS for any past session by ID\n\nThe generated script reconstructs the full session — including capabilities, navigation, clicks, and inputs — as a standalone `import { remote } from 'webdriverio'` file. For BrowserStack sessions it includes the full try/catch/finally with automatic session result marking.\n\n## Troubleshooting\n\n**Browser automation not working?**\n\n- Ensure Chrome, Firefox, Edge, or Safari is installed (Safari requires macOS)\n- Try restarting Claude Desktop completely\n- Check that no other WebDriver instances are running\n\n**Mobile automation not working?**\n\n- Verify Appium server is running: `appium`\n- Check device/emulator is running: `adb devices` (Android) or Xcode Devices (iOS)\n- Ensure correct platform drivers are installed\n- Verify app path is correct and accessible\n\n**Found issues or have suggestions?** Please share your feedback!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdriverio%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebdriverio%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdriverio%2Fmcp/lists"}