k11-appium-qa-mcp
Supports Android apps via UiAutomator2 page sources: inspects screens, checks locators, captures baselines, heals locators in Python and Java (including @AndroidFindBy annotations), and runs an Android emulator end-to-end job in CI.
Core target of the server: heals broken Appium locators for mobile test suites. Works against saved Appium page sources or a live Appium server configured in .qa-mcp/appium.yaml, evaluating UiAutomator2 and XCUITest locators (accessibility id, id, class name, XPath, UiSelector, iOS predicate) offline, and re-running healed tests on the device to verify changes.
Supports iOS apps via XCUITest page sources, healing locators in Python and Java (including @iOSXCUITFindBy annotations) with each platform keeping its own locator.
Device clouds such as Sauce Labs can be used for live Appium sessions by pointing the server's appium.yaml at the cloud's server URL and capabilities, enabling screen capture, inspection and locator healing on cloud-hosted devices.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
k11 Appium QA: self-healing locators for mobile apps
When an app redesign breaks your Appium tests, fix the locators with evidence, not guesses.
Self-healing for mobile tests usually lives inside a paid device cloud, as a black box. k11 Appium QA is open source and runs wherever your tests already run: a laptop with an emulator, your CI, or any device cloud.
Heals on the exact screen the test failed on. A small pytest plugin saves the screen (Appium's page source) at the moment an element isn't found. Healing runs against that screen, with no need to navigate back to it.
Shows its working: confidence, the reasons ("text equivalent: Log in → Sign in", "resource id similar 62%"), the runner-up and alternatives. Accessibility ids are preferred.
Fixes locators where they live: Python
AppiumBy/Bytuples and Page Object constants; JavaAppiumBy/MobileBy/Bycalls and@AndroidFindBy/@iOSXCUITFindByannotations (each keeps its own platform).Verified, not hoped:
heal-cire-runs the healed tests on the device and reverts any change that doesn't pass. When a test gets further and breaks on the next locator, it heals that one too.Android and iOS: UiAutomator2 and XCUITest screens; accessibility id, id, class name, XPath, UiSelector and iOS predicate locators are evaluated offline.
Accessibility check: tappable elements a screen reader can't name, and duplicate accessibility ids. Bad for users, and the reason tests are fragile.
See it heal
A login screen redesign broke three locators in one test and one in another. k11-appium-qa-mcp heal-ci --apply:
3 healed and verified, 1 needs review, 1 failure not caused by locators.
Test
Old locator
New locator
Confidence
Re-run
test_log_in
(AppiumBy.ID, "et_email")
(AppiumBy.ACCESSIBILITY_ID, "email-field")94%
passed
test_log_in
(AppiumBy.ACCESSIBILITY_ID, "password-input")
(AppiumBy.ACCESSIBILITY_ID, "password-field")100%
passed
test_log_in
(AppiumBy.ACCESSIBILITY_ID, "login-button")
(AppiumBy.ACCESSIBILITY_ID, "sign-in-button")77%
passed
Why "sign-in-button"? accessibility id similar (62%) · resource id similar:
btn_login→btn_sign_in· text equivalent: "Log in" → "Sign in" · class matches.Needs a person: the sign-up button lost its accessibility id; best guess
btn_registerat 42%, so it was not changed. Not caused by locators: the title changed from "Welcome back". Untouched; it may be a real change.
The changes land in the Page Object (tests/pages/login_page.py), not scattered across tests.
Related MCP server: Selenium Self-Healing MCP Server
Tools (MCP)
Every tool works on a saved screen (page source XML, e.g. the one saved when a test failed) or on the live device when .qa-mcp/appium.yaml points at an Appium server.
Tool | What it does |
| Elements with locators verified to match exactly one element, most stable first |
| How many elements a locator matches (1 = good) and whether it's visible |
| While tests pass, records each locator's element (per platform) so healing is confident later |
| Finds the intended element and suggests a verified replacement, in Python or Java form |
| Unnamed tappable elements and duplicate accessibility ids |
| Saves the live device's screen for later, device-free work |
| Runs the pytest suite; failures include the locator, line, platform and saved screen |
Command: /heal-mobile-tests, a guided workflow from failing tests to healed, verified locators.
k11 Appium QA doesn't try to replace device-control servers like the official Appium MCP or mobile-mcp; use them to drive and explore the app, and this to keep your existing test suite healthy.
Install
pip install "k11-appium-qa-mcp[live]" # [live] adds the Appium client for live sessions; saved screens need nothing extraClaude Code plugin:
/plugin marketplace add K11-Software-Solutions/k11techlab-appium-qa-mcp
/plugin install appium-qa@k11-appium-qaAny MCP client:
{ "mcpServers": { "appium-qa": { "command": "uvx", "args": ["k11-appium-qa-mcp"] } } }For live sessions, copy docs/appium.example.yaml to .qa-mcp/appium.yaml (server URL and capabilities; secrets as ${ENV:NAME}). Device clouds such as BrowserStack and Sauce Labs work the same way.
Healing in CI
k11-appium-qa-mcp heal-ci # dry run: suggestions only
k11-appium-qa-mcp heal-ci --apply # apply confident changes, verify on the device, revert what failsRuns your pytest suite with the plugin, which saves the screen of every test that fails on a missing element.
Heals each broken locator against that screen and the committed baseline (
.qa-mcp/appium-baselines.json).Applies a change only at 70% confidence or more (
--min-confidence), clearly ahead of the runner-up. Tests that share a broken locator are healed together, with one change.Re-runs the healed tests on the device; a test that now breaks on another locator gets that one healed too (up to five rounds). Every change is kept only if all the tests using it pass.
Leaves failures that aren't about locators alone, and writes
heal-report.md(for the pull request) andheal-report.json.
docs/heal-mobile-locators.yml runs it on an Android emulator in GitHub Actions and opens a pull request. The report uses the same format as k11 Playwright QA and Selenium QA, so the k11 Release Gate reads it as UI evidence.
Java projects: the MCP tools and source rewriting support Java (Page Objects with @AndroidFindBy/@iOSXCUITFindBy, AppiumBy calls). heal-ci currently runs pytest suites; for Maven or Gradle suites, save the screen on failure (driver.getPageSource()) and use heal_locator, or /heal-mobile-tests.
How it's tested
No device needed for most tests: real-format UiAutomator2 and XCUITest page sources, and a fake Appium driver that serves them, run the whole heal-ci loop (run, heal, rewrite, re-run, report) in seconds.
A real emulator on every push:
e2e-android.ymlstarts an Android 14 emulator and an Appium server, reads the built-in Settings app live, captures a baseline and heals a broken locator, both live and from the saved screen.
Safety
Suggestions are never applied silently:
heal_locatornever edits files, andheal-cichanges code only above the threshold and keeps a change only when the tests pass.Screens are parsed with entity expansion and network access disabled; paths must stay inside the project.
Locators from tests and models are parsed, never executed.
Capabilities and credentials come from
.qa-mcp/appium.yamlwith${ENV:NAME}secrets.
Part of the K11 QA suite
Playwright QA · Selenium QA · Appium QA · API Contract QA · API Functional QA · Performance QA · LLM Assure · Release Gate · Release Readiness Agent
Roadmap
heal-cifor Java (Maven/Gradle) suites, with a TestNG/JUnit listener that saves the screen on failureiOS simulator job in CI (macOS runner)
Screenshot similarity as an extra healing signal
Flutter and React Native specifics (semantics labels, testID)
Built by K11 Software Solutions. MIT licensed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
remote debug iOS/Android/Unity/Godot/Flutter/RN/Web on real-device.ui-tree/screenshots/taps,tests.
Playwright selector risk checks with healing suggestions and receipts.
Agents that test your web and mobile app like real users, on every pull request.
Agents that test your web and mobile app like real users, on every pull request.
Related MCP Servers
- AlicenseAqualityDmaintenanceGenerates intelligent Playwright locators with reliability rankings, creates Page Object Models, and runs test automation scripts directly from your IDE or AI assistant.510 npm1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceAutomatically fixes broken Selenium test locators when UI changes occur, reducing test maintenance overhead.2MIT
- AlicenseAqualityCmaintenanceEnables QA to interactively inspect DOM elements in a visible browser, generate resilient Robot Framework locators and Page Objects, and validate selectors via natural language.7BSD 2-Clause "Simplified"
- AlicenseAqualityBmaintenanceProvides AI assistants with real Appium screen data, enabling them to inspect live sessions, retrieve UI hierarchies, suggest robust locators, and interact with mobile applications instead of inventing selectors.11MIT