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.

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]

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.