Analyze Mobile Tool
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.
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
- Authentication - Validates your Axe DevTools Mobile credential: either an
AXE_MOBILE_API_KEYor an OAuth 2.0 access token for an account entitled to Axe DevTools Mobile - Device Setup - Uses
adb(Android) orxcodebuild(iOS) on your machine to install and start Deque's scan server on the device - Accessibility Scan - Scans the screen that's open on the device, using the default Axe DevTools Mobile rules
- 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_KEYto 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-serverfor Android@deque/axe-appium3-webdriveragent-assetsfor 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_KEYto 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 samenpxarguments from step 1 after the--, and leave outAXE_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 statedevice. A state ofunauthorizedmeans the device hasn't accepted the USB debugging prompt yet;offlinemeansadbcan't reach it. - iOS: Run
xcrun simctl list devices bootedto 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 issuesiOS:
Scan the screen on my iPhone simulator for accessibility issuesFor 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.
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.xcodeprojin 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
remediatetool accepts web issues only.
