Skip to main content
Glama
Sign In
MCP Appium

MCP Appium

Official
by appium
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

appium_find_element

Read-only

Find an element by strategy and selector. Pass its ID as elementUUID to interaction tools. Returns driver attributes as JSON.

Instructions

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).

Input Schema

NameRequiredDescriptionDefault
selectorYesSelector for the strategy. Do not pass natural-language descriptions; use appium_ai action=find_element for vision.
strategyYesaccessibility id: cross-platform, fast and stable. id: Android resource-id; iOS accessibility-id alias. iOS prefer accessibility id > -ios predicate string > -ios class chain; Android prefer accessibility id > id > -android uiautomator. Use xpath last (slow/brittle). name: legacy; class name: broad matches; css selector: webview only.
sessionIdNoSession ID; defaults to the active session.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.97.1
    • changedInput schema / properties / selector / description
      Previous value: -"Selector string for the chosen strategy. Do not pass natural-language descriptions of the target here; use appium_ai action=find_element if enabled for vision-based finding."New value: +"Selector for the strategy. Do not pass natural-language descriptions; use appium_ai action=find_element for vision."
    • changedInput schema / properties / strategy / description
      Previous value: -"Locator strategy. Prefer stable identifiers, then platform-native queries; xpath is the last resort.\n- accessibility id: cross-platform, fast and stable when available.\n- id: Android resource-id; an accessibility-id alias on iOS.\n- -ios predicate string: fast native iOS queries on element attributes.\n- -ios class chain: native iOS hierarchy queries.\n- -android uiautomator: native Android queries using UiSelector.\n- xpath: last resort; slow on iOS XCUITest and brittle to layout changes.\n- name: legacy; often aliased on iOS.\n- class name: usually too generic and may match multiple elements.\n- css selector: webview/hybrid web contexts only, not native screens.\niOS prefer accessibility id > -ios predicate string > -ios class chain; Android prefer accessibility id > id > -android uiautomator. Use xpath last on both."New value: +"accessibility id: cross-platform, fast and stable. id: Android resource-id; iOS accessibility-id alias.\niOS prefer accessibility id > -ios predicate string > -ios class chain; Android prefer accessibility id > id > -android uiautomator. Use xpath last (slow/brittle).\nname: legacy; class name: broad matches; css selector: webview only."
  2. Changed3 schema fields changedv1.95.0
    • changedInput schema / properties / selector / description
      Previous value: -"Selector string for the chosen strategy. Do not pass natural-language descriptions of the target here; use appium_ai (action=find_element) for that."New value: +"Selector string for the chosen strategy. Do not pass natural-language descriptions of the target here; use appium_ai action=find_element if enabled for vision-based finding."
    • changedInput schema / properties / sessionId / description
      Previous value: -"Session ID to target. If omitted, uses the active session."New value: +"Session ID; defaults to the active session."
    • changedInput schema / properties / strategy / description
      Previous value: -"Locator strategy. Try in priority order: (1) accessibility id [cross-platform, fastest, most stable], (2) id [Android resource-id; iOS aliases accessibility id], (3) -ios predicate string [iOS native, fast], (4) -ios class chain [iOS native, hierarchy queries], (5) -android uiautomator [Android native, expressive UiSelector], (6) xpath [LAST RESORT — slow on iOS XCUITest, brittle to layout changes], (7) name [legacy; often aliased on iOS], (8) class name [too generic, usually multi-match], (9) css selector [webview/hybrid contexts only]. Platform tips: iOS prefer (1)→(3)→(4); Android prefer (1)→(2)→(5); xpath last on both. For natural-language / vision-based find, use the appium_ai tool (action=find_element), not this one."New value: +"Locator strategy. Prefer stable identifiers, then platform-native queries; xpath is the last resort.\n- accessibility id: cross-platform, fast and stable when available.\n- id: Android resource-id; an accessibility-id alias on iOS.\n- -ios predicate string: fast native iOS queries on element attributes.\n- -ios class chain: native iOS hierarchy queries.\n- -android uiautomator: native Android queries using UiSelector.\n- xpath: last resort; slow on iOS XCUITest and brittle to layout changes.\n- name: legacy; often aliased on iOS.\n- class name: usually too generic and may match multiple elements.\n- css selector: webview/hybrid web contexts only, not native screens.\niOS prefer accessibility id > -ios predicate string > -ios class chain; Android prefer accessibility id > id > -android uiautomator. Use xpath last on both."
  3. First observedv1.92.11

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint, openWorldHint), so the description's job is supplementary. It does add real value: the return shape ('Returns driver attributes as JSON'), the elementResponseAttributes dependency on appium_driver_settings with shouldUseCompactResponses=false, and the caveat against natural-language selectors. It stops short of describing failure behavior when an element is not found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and the returned-UUID contract in the first two sentences, with preference ordering and cross-tool routing after. Dense and mostly waste-free, though the driver-settings aside could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-format burden and does so ('driver attributes as JSON'). Combined with strategy guidance, the scroll alternative, and the vision fallback, an agent has everything needed to select and call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the strategy enum is thoroughly documented in the schema itself (per-platform guidance is already in the enum/param descriptions). The description's strategy preference ordering largely repeats the schema, so it adds direction but little new parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find an element by strategy and selector') and immediately clarifies the downstream contract: the returned element UUID is passed to interaction tools. It is cleanly distinguishable from the sibling appium_find_elements (plural).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to alternatives: appium_gesture action=scroll_to_element for scrolling-until-found, and appium_ai action=find_element for the vision fallback. It also gives a concrete preference ordering (accessibility id > id > platform-native > xpath) with the reason xpath is last resort.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools