Discover and select a device for LOCAL Appium servers ONLY. DO NOT use this tool for REMOTE Appium servers - remoteServerUrl indicates a remote server. WORKFLOW FOR LOCAL SERVERS: 1. ASK THE USER which platform they want (Android or iOS) - do not assume 2. Call this tool with the chosen platform (and iosDeviceType for iOS) 3. If only one device is found, it is auto-selected - proceed to appium_session_management (action=create) (or prepare_ios_simulator for iOS simulators) 4. If multiple devices are found, ask the user which one they want, then call this tool again with deviceUdid 5. After selection, proceed to appium_session_management (action=create) (or prepare_ios_simulator for iOS simulators, then appium_session_management with action=create) WORKFLOW FOR REMOTE SERVERS: - SKIP this tool entirely - Device selection should be handled via capabilities on appium_session_management (action=create) (e.g., appium:deviceName, appium:udid) - The remote Appium server is already configured for specific device(s)

Manage Appium sessions. Use action=create to start a session, attach to connect to an existing one, detach to forget an attached session, delete to stop one, list to see all active sessions, or select to switch the active session.

Control device behavior: lock/unlock the screen, shake the device, or open the notifications panel. Use the action parameter to choose what to do.

Get, set, or reset the device geolocation (GPS coordinates). Works on both iOS (simulators and real devices) and Android (emulators and real devices with mock location enabled). Use action=get to read current coordinates, action=set with latitude/longitude (and optional altitude for Android) to simulate a location, or action=reset to restore the system default. Note: On Android emulators, reset is not supported — use action=set to manually restore coordinates instead. On Android real devices, the mocked location may persist until the GPS cache refreshes.

Get device information, battery status, or current device time in a single call. Use the "action" parameter to select which data to retrieve. Works on both iOS and Android.

Push or pull a file using Appium mobile extensions. action=push uses payloadBase64, action=pull returns contentBase64.

Read or update Appium driver session settings (e.g. idle timeouts, selector waits). Use action=get to return JSON settings; action=update merges a map into the session. Works for embedded UiAutomator2/XCUITest sessions and remote WebDriver clients that support Appium settings.

Prepare an iOS/tvOS simulator for Appium testing in a single call. Automatically boots the simulator, downloads prebuilt WDA (if not cached), and installs/launches WDA on a free per-simulator port (so multiple simulators can run in parallel without colliding on the default 8100). Pass the returned capabilitiesHint (appium:webDriverAgentUrl) to appium_session_management (action=create) so the session reuses this running WDA instead of trying to start its own. Use skipWda=true to only boot without WDA. Set APPIUM_MCP_WDA_APP_PATH to an absolute path to a pre-extracted WebDriverAgentRunner-Runner.app to skip download entirely (useful in environments where external downloads are blocked).

Prepare an iOS real device for Appium testing in a single call. Two-mode flow: (1) Call without provisioningProfileUuid to receive the list of available .mobileprovision profiles — present them to the user (highlight any with recommendedForWda=true) and ask them to pick one. (2) Call again with the chosen UUID to download the matching WebDriverAgent release, package it as an IPA, and resign it with the chosen profile (wildcard "*" profiles are supported — a concrete WDA bundle ID is substituted at sign time). WDA download and unsigned IPA are cached per WDA version; the signed IPA is rebuilt every call. Pass the returned capabilitiesHint to appium_session_management (action=create) so Appium installs and launches the signed prebuilt WDA instead of rebuilding. Requires macOS, Xcode 16+, and a paired developer-mode device.

Perform a touch gesture. Use 'action' to choose: tap, double_tap, long_press, scroll, swipe, pinch_zoom, scroll_to_element, back. Choose scroll vs swipe by intent: scroll to browse content in a list or feed; swipe to dismiss, switch screens, navigate carousels, or pull-to-refresh (speed=fast). For drag-and-drop use appium_drag_and_drop. For custom multi-touch use appium_perform_actions.

Perform a drag-and-drop gesture from a source location to a target location. The gesture: long press the source (default 600ms), drag to the target (default 1200ms), then release. Source and target can each be specified as either an element UUID or coordinates. Useful for reordering lists, moving items, drag-to-delete.

Execute raw W3C Actions API sequences for advanced multi-touch gestures not covered by appium_gesture. Use this for custom multi-finger gestures (rotate, three-finger swipe, edge swipes), complex timing sequences, or any gesture requiring precise control over individual touch points. Prefer appium_gesture for standard gestures (tap, scroll, swipe, pinch) — it handles platform differences automatically.

Find a specific element by strategy and selector which will return a uuid that can be used for interactions.

[PRIORITY 2: Use this to search for a target element.]

Strategy priority: accessibility id > id > platform-native (-ios predicate string / -ios class chain on iOS, -android uiautomator on Android) > xpath (last resort — slow & brittle). See the strategy parameter for the full ranking.

Scrolling until an element appears: use appium_gesture with action=scroll_to_element (same strategy + selector), not this tool.

Vision / natural-language find: use appium_ai with action=find_element, not this tool.

Press navigation keys (BACK, HOME, APP_SWITCH) on Android or physical buttons (HOME, volume, etc.) on iOS/tvOS.

Enter text into an element

Hide the software keyboard or check if it is visible (Android UiAutomator2 / iOS XCUITest). action=hide uses mobile: hideKeyboard; action=is_shown uses mobile: isKeyboardShown.

Get text from an element

Get the value of an element attribute. Use this to check element state (enabled, selected, checked, focused, displayed, clickable) or read properties (name, value, label, content-desc, resource-id, class).

Read or set the device clipboard as plain text (Android UiAutomator2 / iOS XCUITest). action=get returns current text; action=set requires content.

Get the currently active/focused element and return its UUID for follow-up interactions. [PRIORITY 1: Use this first when you need to find what element currently has focus]

Get the page source (XML) from the current screen

Get or set the device/screen orientation. Supports action=get and action=set (LANDSCAPE or PORTRAIT).

Handle system alerts with action=accept|dismiss, or read alert text with action=get_text.

Take a screenshot and save as PNG. Optionally provide elementUUID to capture only that element.

Get the width and height of the device screen in pixels. Useful for calculating coordinates for swipes, taps, and scrolls.

Start or stop screen recording. action=start begins recording; action=stop stops and saves to MP4.

Manage app lifecycle, installation, state, data, and deep links.

Get/update Android app permissions or iOS Simulator privacy services; reset iOS privacy prompts. See action-specific parameters.

Manage Appium contexts with one tool. action=list returns all contexts and current context. action=switch changes to a target context.

Generate locators for all interactable elements on the current page. [PRIORITY 3: Use this for debugging/inspection or when you need comprehensive element info with locator suggestions]

Generate tests for a mobile app: follow the returned instructions to drive the real session with MCP tools (select_device, appium_session_management, appium_find_element, appium_gesture, appium_set_value, etc.), then emit code. Use generate_locators only when you need a full locator snapshot; prefer appium_find_element for normal steps.