Analyze Mobile Tool

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

The analyze_mobile tool scans the screen currently showing on a mobile device for accessibility issues, using Axe DevTools Mobile rules. It works with a connected Android device or emulator, and with a booted iOS simulator or a USB-connected iPhone.

note

analyze_mobile needs an Axe DevTools Mobile subscription. It isn't part of the Free or Premium plans, which cover web scanning.

What It Does

  1. Authentication - Validates your Axe DevTools Mobile credential: either an AXE_MOBILE_API_KEY or an OAuth 2.0 access token for an account entitled to Axe DevTools Mobile
  2. Device Setup - Uses adb (Android) or xcodebuild (iOS) on your machine to install and start Deque's scan server on the device
  3. Accessibility Scan - Scans the screen that's open on the device, using the default Axe DevTools Mobile rules
  4. Results Delivery - Returns violations, incomplete checks, and passes, each with enough location detail for your agent to find the view in your source code

Requirements

The tool appears in your MCP client only when all of the following are true:

  • The npm distribution. Mobile scanning drives a device or simulator connected to your machine, which a container can't reach.
  • An Axe DevTools Mobile credential. Set AXE_MOBILE_API_KEY to an Axe DevTools Mobile API key from the Axe Account Portal, or sign in with OAuth 2.0 using an account entitled to Axe DevTools Mobile.
  • The scanner packages, installed alongside the server. See Setup.

Each platform also needs tools on the machine that runs the server:

Platform Host Needs
Android macOS, Windows, Linux Android SDK Platform-Tools, with adb on your PATH. A device with USB debugging turned on, or a running emulator.
iOS simulator macOS only Xcode (not just the Command Line Tools), selected with xcode-select. A booted simulator.
iPhone (physical) macOS only Xcode, an iPhone connected by USB cable with Developer Mode on, and an Apple developer account to sign WebDriverAgent. See Scanning a physical iPhone.

Setup

1. Add the scanner packages to your server command

The npm distribution runs the server with npx, so add the scanner packages to the same command:

  • @deque/axe-appium3-uiautomator2-server for Android
  • @deque/axe-appium3-webdriveragent-assets for iOS

On macOS, install both, even if you only scan one platform. On Windows and Linux, install only the Android package. The server looks for both at startup, and if either is missing it doesn't offer the tool.

macOS, both platforms:

{
  "mcpServers": {
    "axe-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "axe-mcp-server",
        "-p",
        "@deque/axe-appium3-uiautomator2-server@^1.7.0",
        "-p",
        "@deque/axe-appium3-webdriveragent-assets@^1.7.0",
        "axe-mcp-server"
      ],
      "env": {
        "AXE_MOBILE_API_KEY": "${AXE_MOBILE_API_KEY}"
      }
    }
  }
}

Windows and Linux, Android only:

"args": [
  "-y",
  "-p",
  "axe-mcp-server",
  "-p",
  "@deque/axe-appium3-uiautomator2-server@^1.7.0",
  "axe-mcp-server"
]

The example uses Claude Code's .mcp.json format. Put the same args in your own client's configuration; see the setup guide for Claude Code, Cursor, or VS Code with Copilot. If a package is missing, the server names it in its startup log.

2. Set your credential

Set one of the following:

  • API key: Set AXE_MOBILE_API_KEY to an Axe DevTools Mobile API key from the Axe Account Portal.
  • OAuth 2.0: Sign in once with npx @deque/axe-auth login, using an account entitled to Axe DevTools Mobile. Then run the server under @deque/axe-auth run: put the same npx arguments from step 1 after the --, and leave out AXE_MOBILE_API_KEY. See OAuth 2.0.

If you also use the web tools with an API key, set AXE_API_KEY alongside AXE_MOBILE_API_KEY. An API key can't be combined with AXE_ACCESS_TOKEN; see Configuration Reference.

3. Connect a device

Check that the device is visible before you scan:

  • Android: Run adb devices. Your device or emulator should be listed with the state device. A state of unauthorized means the device hasn't accepted the USB debugging prompt yet; offline means adb can't reach it.
  • iOS: Run xcrun simctl list devices booted to see booted simulators. A physical iPhone should appear in Xcode's Devices and Simulators window.

4. Run a first scan

Open the screen you want to scan, then tell your agent.

Android:

Scan the screen on my Android emulator for accessibility issues

iOS:

Scan the screen on my iPhone simulator for accessibility issues

For iOS, your agent sends the app's bundle ID with the scan. It can look it up in your Xcode project, or you can name it in the prompt.

tip

The first iOS scan builds WebDriverAgent, which can take up to 15 minutes. Later scans on the same device are much faster.

Parameters

Parameter Required Description
platform Yes "android" or "ios"
bundleId Yes (iOS only) The bundle ID of the app on screen, such as com.example.app
udid No (iOS only) The UDID of the simulator or iPhone to scan. When omitted, the server uses the booted simulator, or else the connected iPhone.

Choose an Android device. There's no device parameter for Android. When one device or emulator is ready, the server scans it. When several are ready, set ANDROID_SERIAL in the server's environment to the serial adb devices lists for the one you want.

Find the bundle ID. It's the PRODUCT_BUNDLE_IDENTIFIER in your Xcode project, or the app's Info.plist. Tell your agent where to look, or include the bundle ID in your prompt.

Prompt your AI agent in natural language. The agent translates your intent into the tool call:

Scan the app on my iPhone simulator for accessibility issues. The bundle ID
is in ios/MyApp.xcodeproj.

The agent resolves the prompt and calls analyze_mobile with a payload similar to:

{
  "platform": "ios",
  "bundleId": "com.example.myapp"
}

Results

The tool returns a summary of the scan and three lists of findings: violations, incomplete, and passes.

Findings

Each entry in violations, incomplete, and passes has these fields:

Field Description
ruleId The Axe DevTools Mobile rule, such as ColorContrast
summary A short description of the rule
impact Critical, Serious, Moderate, or Minor
standard The standard the rule maps to, such as WCAG 2.1
successCriteria The success criterion the rule maps to, such as 1.4.3
identifier The view's developer-set identifier: accessibilityIdentifier on iOS, or the resource ID on Android, shown as #name, or null when the view has none
viewPath The path from the root of the screen to the view, as a list of class names, with each view's identifier in parentheses when it has one, such as Button(#login_button)
bounds The view's position on screen, as left, top, right, and bottom
accessibleName The name assistive technology announces for the view, or null
props Rule-specific evidence, such as the colors and ratio a contrast check measured, with fields that vary by rule

identifier and viewPath are how your agent finds the view in your source code. An identifier is the most direct match: search the project for it. When a view has no identifier, viewPath shows where it sits, by class name and by the nearest ancestors that do have one.

Rules

analyze_mobile runs the Axe DevTools Mobile rules for each platform:

analyze_mobile runs the default Axe DevTools Mobile rules. It doesn't apply your organization's mobile global rule configuration yet.

Advanced Rules and Intelligent Guided Tests are web-only and don't run in mobile scans.

Scanning a Physical iPhone

A physical iPhone needs a little more than a simulator:

  • Connect it with a USB cable. A phone paired with your Mac over Wi-Fi can't be scanned.
  • Turn on Developer Mode under Settings > Privacy & Security > Developer Mode, then restart the phone.
  • Trust the Mac. Unlock the phone and tap Trust when it asks.
  • Keep it unlocked, with the screen on, while scanning.
  • Sign WebDriverAgent with your Apple developer account. The server doesn't set a signing identity for you. Open WebDriverAgent.xcodeproj in Xcode, choose your Team under Signing & Capabilities, and let Xcode create a provisioning profile.

When signing fails, the scan returns a message saying what's missing, such as a development team or a provisioning profile.

Troubleshooting

If analyze_mobile doesn't appear in your client, check Requirements and the server's startup log, which names any missing scanner package. Restart your client's MCP session after you change the configuration.

For other problems, the server's error messages say what's wrong. The ones that need more than the message:

Message What to do
AXE_MOBILE_API_KEY is not supported in the Docker distribution The server refuses to start in Docker with a mobile key. Switch to the npm distribution.
No Android device or emulator found, or the device is not ready Start an emulator, or connect a device with USB debugging on and accept the prompt on the device. Check adb devices: the state should be device, not unauthorized or offline.
More than one Android device is ready Set ANDROID_SERIAL to the serial of the device to scan, or disconnect the others.
The device named by ANDROID_SERIAL is not ready Compare ANDROID_SERIAL with the left column of adb devices.
An iOS scan needs the bundleId of the app on screen Include the bundle ID in your prompt, or tell your agent where to find it.
xcodebuild not found Install Xcode from the App Store. If it's installed, select it: sudo xcode-select -s /Applications/Xcode.app. The Command Line Tools alone aren't enough.
The iPhone is not connected by USB A phone paired over Wi-Fi can't be scanned. Connect it with a USB cable.
Code signing failed: … Sign WebDriverAgent with your Apple developer account. See Scanning a physical iPhone.
The device has Developer Mode disabled / has not trusted this Mac / appears to be locked Follow the steps in Scanning a physical iPhone.
The on-device scan server did not start within …ms Raise MOBILE_SERVER_READY_TIMEOUT_MS and try again.
This account does not have an active axe DevTools Mobile subscription Ask your account administrator to add an Axe DevTools Mobile subscription, then start a new session.
This API key belongs to a different product Make sure AXE_MOBILE_API_KEY holds an Axe DevTools Mobile key and AXE_API_KEY holds a web key, then start a new session.
`analyze` needs a web credential (or remediate, igt) Only AXE_MOBILE_API_KEY is set, which doesn't authorize the web tools. Add AXE_API_KEY, or switch to OAuth and remove AXE_MOBILE_API_KEY, then start a new session.

For any other failure, set LOG_LEVEL=debug in the server's environment. For an iOS build failure, the debug log includes Xcode's own output. See also the general Troubleshooting page.

Limitations

  • One screen per call. The tool scans what's on screen and doesn't navigate the app. Open each screen yourself, then scan it.
  • One scan at a time, per machine. The server runs one mobile scan at a time, and Android scans use a fixed local port, so run only one mobile-scanning server per machine.
  • No Advanced Rules or Intelligent Guided Tests. Both are web-only.
  • No screenshot. Unlike analyze, the tool doesn't return an image of the screen.
  • No progress updates during the first iOS build. The call stays quiet until WebDriverAgent is built and the scan finishes.
  • No mobile remediation. The remediate tool accepts web issues only.