Skip to main content
Glama
appium

MCP Appium

Official
by appium
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

appium_session_management

Destructive

Manage Appium sessions: create, attach, detach, delete, list, or select active sessions for mobile testing.

Instructions

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
actionYescreate: Create a new Appium session. DEFAULT MODE (no remoteServerUrl): use unless the user explicitly provides a server URL. - Drivers run embedded inside this MCP server; no separate Appium process is needed. - Use select_device tool FIRST to discover devices. Ask for platform/device if unknown; do not assume a platform. - For iOS simulators, run prepare_ios_simulator before creating the session. - Call appium_session_management action=create with the selected platform and any returned capabilitiesHint serialized as capabilities. - Do NOT pass remoteServerUrl for local/embedded mode. NEVER invent a localhost URL. REMOTE SERVER MODE (only when user explicitly provides a URL): - Skip local device selection and preparation; do not call select_device. - Infer platform and device type from the request when possible; ask if unclear. - Use platform=general for non-Android/iOS drivers (Windows, macOS, custom); capabilities pass through without platform defaults. - Call appium_session_management action=create with platform, remoteServerUrl, and the requested capabilities. - Example: "create an iOS session at http://localhost:4723" means platform=ios and remoteServerUrl=http://localhost:4723; do not discover local devices. attach: connect to an existing remote Appium session without taking ownership of its lifecycle. Requires remoteServerUrl and sessionId; capabilities are fetched from the remote server. detach: remove an attached session from MCP without deleting the real remote session. Defaults to the active session. delete: delete a session and clean up resources. Defaults to the active session. list: list managed sessions with active flag, ownership, and current context. select: set sessionId as the active session for subsequent calls; requires sessionId.
platformNoRequired for create. For local sessions, match the platform selected via select_device. For remote sessions, infer from the request; general supports non-Android/iOS drivers (Windows, macOS, custom) and requires remoteServerUrl.
sessionIdNoRequired for attach and select: the existing session to connect to or activate. For delete: session to delete. For detach: attached session to forget without stopping it. Delete/detach default to the active session when omitted.
capabilitiesNoOptional W3C capabilities as a JSON string, e.g. '{"appium:app":"/path/to/app","appium:platformVersion":"17.0"}'. Create: overrides defaults for ios/android; passed through as-is for general. Common keys: appium:app, appium:deviceName, appium:udid, appium:platformVersion, appium:bundleId. When using capabilitiesHint from a preparation tool, serialize the full object to JSON; preserve boolean and numeric values. Attach: optional fallback values (e.g. '{"platformName":"iOS"}'); capabilities fetched from the server take precedence.
remoteServerUrlNoRemote Appium server URL for create or attach (e.g. http://localhost:4723). Omit to use local server for create.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.95.0
    • changedInput schema / properties / action / description
      Previous value: -"Action to perform. create: Create a new Appium session with Android, iOS or any device/driver Appium supports.\n      DEFAULT MODE (no remoteServerUrl) — USE THIS UNLESS THE USER EXPLICITLY PROVIDES A SERVER URL:\n      - Drivers run embedded inside this MCP server; no separate Appium process is needed\n      - Use select_device tool FIRST to discover devices and let the user choose platform and device\n      - Then call action=create with the selected platform (do NOT pass remoteServerUrl)\n      - For iOS simulators, call prepare_ios_simulator before action=create\n      - DO NOT assume or default to any platform\n      - NEVER invent a localhost URL (e.g. http://localhost:4723) — omitting remoteServerUrl IS the local/embedded mode\n      REMOTE SERVER MODE (only when user explicitly provides a URL like http://localhost:4723):\n      - SKIP select_device tool entirely\n      - Infer the platform from the user's request (e.g., 'ios', 'android', or 'general')\n      - If platform is 'general', treat the provided capabilities as a pass-through W3C/Appium capability set (useful for non-Android/iOS drivers like Windows, macOS, or custom drivers)\n      - Infer device type from context when possible (e.g., 'simulator', 'real device')\n      - Call session with action=create directly with platform, remoteServerUrl, and any other capabilities from the user's request\n      - Example: User says 'start session with http://localhost:4723 for ios with iphone 17' → infer platform='ios' and call session(action=create) with remoteServerUrl and platform parametersattach: Attach MCP Appium to an existing remote Appium session without taking ownership of its lifecycle. Requires remoteServerUrl and sessionId. Always pass capabilities with at least platformName (e.g. '{\"platformName\":\"iOS\"}' or '{\"platformName\":\"Android\"}') so the client is configured with the correct protocol commands.detach: Remove an attached Appium session from MCP Appium without deleting the real remote session. Defaults to the active session.delete: Delete a mobile session and clean up resources. If sessionId is omitted, deletes the active session.list: List all active Appium sessions managed by this MCP server, including active flag, ownership, and current context.select: Set an existing Appium session as the active session for subsequent tool calls (requires sessionId)."New value: +"create: Create a new Appium session.\nDEFAULT MODE (no remoteServerUrl): use unless the user explicitly provides a server URL.\n- Drivers run embedded inside this MCP server; no separate Appium process is needed.\n- Use select_device tool FIRST to discover devices. Ask for platform/device if unknown; do not assume a platform.\n- For iOS simulators, run prepare_ios_simulator before creating the session.\n- Call appium_session_management action=create with the selected platform and any returned capabilitiesHint serialized as capabilities.\n- Do NOT pass remoteServerUrl for local/embedded mode. NEVER invent a localhost URL.\nREMOTE SERVER MODE (only when user explicitly provides a URL):\n- Skip local device selection and preparation; do not call select_device.\n- Infer platform and device type from the request when possible; ask if unclear.\n- Use platform=general for non-Android/iOS drivers (Windows, macOS, custom); capabilities pass through without platform defaults.\n- Call appium_session_management action=create with platform, remoteServerUrl, and the requested capabilities.\n- Example: \"create an iOS session at http://localhost:4723\" means platform=ios and remoteServerUrl=http://localhost:4723; do not discover local devices.\nattach: connect to an existing remote Appium session without taking ownership of its lifecycle. Requires remoteServerUrl and sessionId; capabilities are fetched from the remote server.\ndetach: remove an attached session from MCP without deleting the real remote session. Defaults to the active session.\ndelete: delete a session and clean up resources. Defaults to the active session.\nlist: list managed sessions with active flag, ownership, and current context.\nselect: set sessionId as the active session for subsequent calls; requires sessionId."
    • changedInput schema / properties / capabilities / description
      Previous value: -"Optional W3C capabilities for create. Provide as a JSON string (e.g. '{\"appium:app\":\"/path/to/app\",\"appium:platformVersion\":\"17.0\"}'). For create: applied on top of defaults for ios/android, or used as-is for general. Common: appium:app, appium:deviceName, appium:platformVersion, appium:bundleId. When passing from a capabilitiesHint result, serialize the full object to JSON — do NOT drop boolean or numeric values. For attach: always include platformName (\"iOS\" or \"Android\") so the WebDriver client loads the correct Appium protocol commands (e.g. '{\"platformName\":\"iOS\"}')."New value: +"Optional W3C capabilities as a JSON string, e.g. '{\"appium:app\":\"/path/to/app\",\"appium:platformVersion\":\"17.0\"}'. Create: overrides defaults for ios/android; passed through as-is for general. Common keys: appium:app, appium:deviceName, appium:udid, appium:platformVersion, appium:bundleId. When using capabilitiesHint from a preparation tool, serialize the full object to JSON; preserve boolean and numeric values. Attach: optional fallback values (e.g. '{\"platformName\":\"iOS\"}'); capabilities fetched from the server take precedence."
    • changedInput schema / properties / platform / description
      Previous value: -"Required for create. For local servers, must match the platform selected via select_device. Use \"general\" for non-Android/iOS drivers (Windows, macOS, custom). For remote servers, infer from context."New value: +"Required for create. For local sessions, match the platform selected via select_device. For remote sessions, infer from the request; general supports non-Android/iOS drivers (Windows, macOS, custom) and requires remoteServerUrl."
    • changedInput schema / properties / sessionId / description
      Previous value: -"For attach: existing session to connect to. For delete: session to remove (defaults to active). For detach: attached session to remove from MCP (defaults to active). For select: session to activate. Required for attach and select."New value: +"Required for attach and select: the existing session to connect to or activate. For delete: session to delete. For detach: attached session to forget without stopping it. Delete/detach default to the active session when omitted."
  2. First observedv1.92.11

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (destructiveHint=true), the description discloses lifecycle semantics: detach 'remove[s] an attached session... without deleting the real remote session', delete 'clean[s] up resources' and defaults to the active session, and attach fetches capabilities from the server. These ownership and defaulting behaviors are not encoded in the schema or annotations.

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?

The tool-level description is concise and front-loaded with all six actions. However, the action parameter description is a large wall of text that absorbs nearly all workflow guidance, and the tool description carries little of the load. Every sentence is informative, but the distribution is uneven.

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

Completeness4/5

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

For a six-action, dual-mode (local/remote) tool with no output schema, the description is remarkably complete: prerequisites, mode selection, parameter roles, and defaults are all covered. Minor gaps remain in return-value shapes (e.g., what create or list returns), but nothing essential to invoking the tool correctly is missing.

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

Parameters5/5

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

Although schema coverage is 100%, the parameter descriptions add substantial semantics: the action enum embeds complete per-action workflows, sessionId documents default-on-omit behavior per action, capabilities explains serialization rules and precedence, and remoteServerUrl distinguishes local vs remote modes.

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?

The description opens with a specific verb+resource statement ('Manage Appium sessions') and enumerates all six operation modes (create, attach, detach, delete, list, select), each with a distinct purpose. It differentiates cleanly from siblings like appium_app_lifecycle or select_device, which do not manage session lifecycle.

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?

The action parameter description provides explicit when-to-use guidance: local/embedded mode vs remote server mode, when to call select_device and prepare_ios_simulator first, when to use platform=general, and a concrete example ('create an iOS session at http://localhost:4723'). It also names the alternative preparation tools, leaving nothing to inference.

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