Discover/select a LOCAL device. Ask for platform if unknown; one device is auto-selected. For multiple devices, ask the user to choose, then pass deviceUdid. Next: prepare_ios_simulator for iOS simulators, then appium_session_management action=create. Skip for REMOTE servers: pass device capabilities (appium:deviceName/appium:udid) and the user-provided remoteServerUrl to session creation.

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.

Boot an iOS/tvOS simulator, download/cache WDA, and launch it on a free per-simulator port. Pass capabilitiesHint (appium:webDriverAgentUrl) to appium_session_management action=create to reuse WDA. skipWda=true only boots. APPIUM_MCP_WDA_APP_PATH can point to an extracted WebDriverAgentRunner-Runner.app (absolute path) to skip download.

Prepare signed WDA for a real iOS device. Omit provisioningProfileUuid to list profiles; ask the user to choose, highlighting recommendedForWda. Pass the chosen UUID to download, package, and sign WDA; wildcard profiles use a concrete WDA bundle ID. Downloads/unsigned IPA are cached per version; signing always reruns. Pass capabilitiesHint to appium_session_management action=create to install/launch the signed WDA. 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 an element by strategy and selector. Pass its ID as elementUUID to interaction tools. Returns driver attributes as JSON. For drivers supporting elementResponseAttributes, use appium_driver_settings to configure it with shouldUseCompactResponses=false. Prefer accessibility id > id > platform-native > xpath (last resort: slow/brittle). See strategy for platform-specific guidance. To scroll until a target is found, use appium_gesture action=scroll_to_element with the same strategy and selector, rather than repeatedly calling this tool. Vision fallback: appium_ai action=find_element (if enabled).

Find all elements matching a strategy and selector. Returns JSON {elements: [{elementId, attributes?}]}; no matches returns {elements: []}. Pass an elementId as elementUUID to interaction tools. Additional driver attributes are preserved. For drivers supporting elementResponseAttributes, use appium_driver_settings to configure it with shouldUseCompactResponses=false. Use appium_find_element when only one match is needed.

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 current-screen XML. saveToFile=true returns server-local path/bytes and enables selector/pattern summaries.

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.

Compact one-line-per-element view of the current screen (class, id, desc, text, flags, center). Far cheaper than page source or generate_locators. Use diff=true after an action.

Poll until a locator is present (or gone). Use instead of retrying find_element after navigation.

Count matches for each locator on the live screen. Only a count of exactly 1 is safe to put in test code; >1 is ambiguous, 0 is absent.

Run up to 25 steps (tap, type, wait, read, back, pause) in ONE call and return per-step results plus a compact screen summary. Locators: id=, desc=, text=, xpath=, uia=, pred=. Taps/types wait up to 10s for the element by default.

Classify the current screen (form, list, dialog, login...) and summarise inputs, buttons, navigation, keyboard/dialog state, below-the-fold content and suggested next actions. One call replaces page source + several finds.

Find target element(s) by description and return validated locator candidates, each with live match count (1 = unique), a 0-100 stability score and warnings (value-dependent ids, positional xpath, hidden target). Recommended locator is first. Counts come from the current screen, so re-verify after navigation.

Failure intelligence: after a step fails, checks session liveness, app state, current screen (dialog, keyboard, hidden/ambiguous/disabled target) and logcat crash/ANR/network signals, then returns evidence, likely causes with confidence, next steps and safe recovery. Read-only; never retries or changes state.

Diagnose a session: device state (adb), Appium server (remote), session liveness, app state and foreground, ANR dialog. Returns the failure kind with signals and whether replacing the session would help. With recover=true and only for a recoverable failure (dead session or driver), replaces the session once, bounded to 2 attempts per 10 minutes, never touches other sessions, never resets app data, relaunches the app and verifies the new session. Cloud and attached sessions are not replaced.

Generate current-page locator candidates for inspection. Defaults: controls for UiAutomator2/XCUITest/Web; all elements except hierarchy for other native drivers.

Return a workflow to execute the scenario with MCP tools, then generate test code from observed interactions. Prefer appium_find_element; generate_locators is for broad inspection.