appium-mcp

When enabled, appium-mcp creates spans for MCP tool calls, prompt loads, resource reads, and resource template reads. Error status is recorded for thrown operation errors and MCP tool results marked withisError. Span attributes intentionally avoid raw screenshots, XML page source, prompts, credentials, and other high-cardinality or sensitive payloads.

Tool spans include payload-free result-size attributes:mcp.tool.result.content_count,content_types,text_chars,resource_count,resource_text_chars,image_count,audio_count,base64_chars, andbase64_bytes_estimate(all prefixed withmcp.tool.result.).content_typescontains only known MCP types orother; payload values, resource URIs, MIME types, and unknown type strings are never recorded. Sizes are counted directly from known result fields without serializing or copying the complete result.

For local trace inspection, use the Jaeger setup intools/telemetry:

Then openhttp://127.0.0.1:16686and run appium-mcp with the environment values intools/telemetry/jaeger.env.

Create acapabilities.jsonfile to define your device capabilities:

{ "android": { "appium:app": "/path/to/your/android/app.apk", "appium:deviceName": "Android Device", "appium:platformVersion": "11.0", "appium:automationName": "UiAutomator2", "appium:udid": "your-device-udid" }, "ios": { "appium:app": "/path/to/your/ios/app.ipa", "appium:deviceName": "iPhone 15 Pro", "appium:platformVersion": "17.0", "appium:automationName": "XCUITest", "appium:udid": "your-device-udid" }, "general": { "platformName": "mac", "appium:automationName": "mac2", "appium:bundleId": "com.apple.Safari" } }

Set theCAPABILITIES_CONFIGenvironment variable to point to your configuration file.

Platform names and "general" mode

- You can pass any platform name toappium_session_management(action=create).
- If the platform isiosorandroid, the server builds capabilities for that platform (including selected device info when local).
- If the platform is any other value, it is treated internally asgeneral:

- The session will use the providedcapabilitiesexactly as given, or

- IfCAPABILITIES_CONFIGis set, it will merge with thegeneralsection from your capabilities file.

Integrator notes (sessions, transport, logging)

ForCI,device farms, ormulti-sessionsetups:

The process keeps oneactiveAppium session; tools use it whensessionIdis omitted. If a tool call does not include asessionId, it will target the active session instead of a specific one. If more than one session exists (seeappium_session_managementwithaction=list), passsessionIdon every tool callthat must target a specific session. Do not assume the active session is stable if other clients or flows can create, select, or delete sessions.

IfAPPIUM_MCP_PERSIST_REMOTE_SESSIONS_PATHis set, MCP Appium persistsattached remote sessionsto that directory as JSON files. The path may be absolute or relative to the current working directory. Each session is stored under a canonical filename derived from a hash of thesessionId; older legacy filenames are migrated, and duplicate files for the same session are removed when the directory is read. When a persisted attached session is used again, the server tries to reattach to the remote Appium session; unreachable entries are pruned automatically.

When the MCPclient disconnects, the serverdeletes only MCP-owned sessionsit is tracking (AppiumdeleteSessionfor each, viasafeDeleteAllSessions).Attachedsessions (ownership=attached) are intentionally left on the remote Appium server. Transports that drop often—httpStreambehind proxies, idle timeouts, or flaky clients—canwipe owned automationin one go under the default policy.stdiois usually safer for a single long-lived operator; if you usehttpStream, expect reconnects to requirenew owned sessionswhere applicable.

Forgrids, cloud labs, or CI, preferremoteServerUrlplus explicitcapabilitiesonappium_session_management(action=create)—for exampleappium:udid, app path or id, platform version—rather than depending on local discovery.select_deviceis geared towardlocalADB / simulator picking; use it as adev convenience, not the main path for allocated remote devices.

Tool calls are logged with argumentredactionimplemented viaJSON.stringify. Oversized payloads (especially longbase64 strings, e.g., screenshot/image payloads, and also very largecapabilitiesobjects) costCPUandlog volume. PreferCAPABILITIES_CONFIGand avoid passing large inline blobs in tool arguments when possible.

Set theSCREENSHOTS_DIRenvironment variable to specify where screenshots are saved. If not set, screenshots are saved to the current working directory. Supports both absolute and relative paths (relative paths are resolved from the current working directory). The directory is created automatically if it doesn't exist.

Screen recordings are saved as MP4 files to the same directory as screenshots (SCREENSHOTS_DIR, oros.tmpdir()if not set).

To start recording, callappium_screen_recordingwithaction="start". You may providetimeLimitin seconds to limit the maximum recording duration, but the start call still returns immediately. To finalize the recording, save the video, and receive the file path, callappium_screen_recordingagain withaction="stop".

Configure AI-powered element finding using vision models. When enabled, a separate tool —appium_ai— is registered alongsideappium_find_element. It exposesaction=find_element, which locates UI elements from natural-language descriptions and returns a coordinate UUID (ai-element:x,y:bbox) that can be passed toappium_gesture(tap/double_tap/long_press).

This feature is opt-in.WhenAI_VISION_ENABLEDis unset orfalse, theappium_aitool isnot registeredand the LLM has no way to invoke vision-based finding — keepingappium_find_elementpurely traditional. This deliberate gating prevents the model from defaulting to a slow, paid vision call when a stable locator (accessibility id, resource-id, etc.) would do the job.

{ "appium-mcp": { "env": { "ANDROID_HOME": "/path/to/android/sdk", "AI_VISION_ENABLED": "true", "AI_VISION_API_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1", "AI_VISION_API_KEY": "your_api_key_here" } } }

IfAI_VISION_ENABLED=trueis set without both API vars, the server fails to start with a clear error message — misconfiguration is surfaced immediately rather than mid-test.