Developer Documentation

Mobile MCP Server

Introduction

The Evinced Mobile MCP Server allows mobile developers to analyze their apps for accessibility during development. It enables your coding agent to run Evinced accessibility scans and provides the details required to properly handle detected accessibility issues.

Overview

Evinced Mobile MCP Server provides MCP tools and prompts that enable AI coding agents to analyze mobile applications for accessibility issues and guide the remediation process.

MCP Tools

evinced_accessibility_analyze

Analyzes a mobile screen for accessibility issues using Evinced's accessibility engine. Returns a comprehensive report with identified issues, their severity levels, and recommendations for remediation.

Parameters:

  • device (string, required): The device identifier to use. Use your available device MCP tools or CLI commands to find device identifiers.

Returns: A report detailing detected accessibility issues, including the necessary information to locate and resolve them.

Example Usage:

1Use evinced_accessibility_analyze with device "iPhone 15 Pro"

MCP Prompts

evinced_remediate

A guidance prompt that provides step-by-step instructions for analyzing and remediating mobile app accessibility issues. This prompt helps AI agents follow a structured workflow when handling accessibility tasks.

What it provides:

  • Step-by-step remediation workflow
  • Prioritization guidelines for accessibility issues
  • Element identification strategies
  • Verification procedures
  • Best practices for maintaining functionality while fixing accessibility issues

When to use:

  • When you need guidance on the complete accessibility remediation process
  • When you want to ensure all steps are followed in the correct order
  • When working on complex accessibility remediation tasks

evinced_create_rules

A prompt that helps create agent-specific rules files for your project. These rules guide AI agents on how to use Evinced Mobile MCP and handle accessibility issues appropriately.

What it provides:

  • Instructions for finding existing rules files in your project
  • Format-specific guidance based on your AI agent
  • Pre-configured rules for using Evinced Mobile MCP
  • Safety guidelines and workflow recommendations

Use it once while setting up Evinced Mobile MCP for the first time in a project.

Installation

Prerequisites

Evinced Mobile MCP supports a variety of coding agents and development environments. The minimum requirement is that your app is running on your device or simulator/emulator. Evinced Mobile MCP analyzes your app at runtime, so the application must be running in the foreground.

To enable the full development cycle and ensure Evinced Mobile MCP works effectively, depending on your use case, your coding agent should be able to:

  • Build and run your application.
  • Navigate between screens using automation or deep links to the screens you wish to test.

Evinced Mobile MCP is tested for compatibility with the following iOS MCPs:

Platform Setup

iOS Setup

iOS is supported on both simulators and physical devices via WebDriverAgent (WDA). Before the MCP server can control iOS devices, WebDriverAgent must be running on the target device or simulator.

iOS Simulator Setup

  1. Launch iOS Simulator

    • Launch iOS Simulator on your macOS and boot a simulator
    • Note: If multiple simulators are detected, the MCP will use the first one listed

  2. Launch WebDriverAgent

    1# Clone WebDriverAgent if you haven't already
    2git clone --depth 1 https://github.com/appium/WebDriverAgent.git
    3cd WebDriverAgent
    4

    5# Start WDA as an XCUITest, replace 'iPhone 16' with your simulator name
    6xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'platform=iOS Simulator,name=iPhone 16' test

  3. Verify Setup

    • Try the prompt list simulators in your coding agent
    • You should receive a message saying your simulator is available

iOS Physical Device Setup

  1. Verify Device Connection

    • Make sure developer mode is enabled on your device
    • Ensure the device is connected via USB
    • Verify the device is recognized by Xcode (you can check in Xcode's Devices and Simulators window)

  2. Get Device UDID

    • Open Xcode and go to Window → Devices and Simulators
    • Select your connected device
    • Copy the Identifier (UDID) from the device information

  3. Configure WebDriverAgent Bundle Identifier

    • Clone WebDriverAgent if you haven't already:

      1git clone --depth 1 https://github.com/appium/WebDriverAgent.git
      2cd WebDriverAgent

    • Open WebDriverAgent.xcodeproj in Xcode

    • Replace the bundle identifier with a unique one

    • You need an Apple Developer account (you can enroll for free as an individual)

  4. Launch WebDriverAgent

    1# Start WDA as an XCUITest, replace '000000000000000000000000' with your device UDID
    2xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'platform=iOS,id=000000000000000000000000' test

  5. Verify Setup

    • Try the prompt list devices in your coding agent
    • You should receive a message saying your iPhone with the UDID is available

Port Configuration (Optional)

Different tools launch WebDriverAgent on different ports:

  • mobile-mcp (via mobilecli) uses port 13001
  • Manual WDA from Xcode uses port 8100

To ensure compatibility with both approaches, evinced-mobile-mcp automatically discovers the active WDA port. If you need to specify a specific port, set the WDA_PORT environment variable:

1{
2  "mcpServers": {
3    ...
4    "evinced-mobile-mcp": {
5      "command": "npx",
6      "args": ["-y", "@evinced/mcp-server-mobile@latest"],
7      "env": {
8        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
9        "EVINCED_API_KEY": "YOUR_API_KEY",
10        "WDA_PORT": "8100"
11      }
12    }
13  }
14}

Android Setup

Android is supported on both emulators and physical devices connected via Android Studio or via standalone ADB.

Android Studio setup

  1. Install Android Studio

    • Add ANDROID_HOME to system variables pointing to the Android SDK location. The SDK location can be found in Android Studio under Tools → SDK Manager → Android SDK Location.

  2. [Emulator] Create Virtual Device

    • Make sure the virtual device is running

  3. [Physical Device] Verify Device Connection

    • Make sure developer mode is enabled on your device and the USB Debugging option in the settings is on
    • Ensure the device is connected via USB
    • Verify the device is recognized by Android Studio

  4. Verify Setup

    • Try the prompt list connected Android devices in your coding agent
    • You should receive a message saying your Android device/emulator is available

Standalone ADB setup

  1. Download Android Tools

    • Open the official download page: Platform tools
    • Download the package for your OS (Windows, Mac, or Linux)
    • Extract the ZIP file to a location of your choice
    • Add platform tools to PATH by adding the install directory to ~/.zshrc or ~/.bash_profile

  2. Verify ADB installation

    • Open a new Terminal window or run source ~/.zshrc (or source ~/.bash_profile)
    • Run adb --version in the Terminal. You should see ADB tool's basic information printed

  3. [Physical Device] Verify Device Connection

    • Make sure developer mode is enabled on your device and the USB Debugging option in the settings is on
    • Ensure the device is connected via USB

  4. Verify Setup

    • Try the prompt list connected Android devices in your coding agent
    • You should receive a message saying your Android device/emulator is available

Installation from Evinced Restricted NPM

Authorize Evinced Repository

The Evinced mobile MCP server package is distributed via the Evinced repository. Please ensure that your .npmrc file contains the following template:

1@evinced:registry=https://evinced.jfrog.io/artifactory/api/npm/restricted-npm/
2//evinced.jfrog.io/artifactory/api/npm/restricted-npm/:_authToken=<your-jfrog-token>
3//evinced.jfrog.io/artifactory/api/npm/restricted-npm/:always-auth=true

Your Evinced JFROG token should be provided to you by your Evinced contact.

Add Evinced Mobile MCP to your IDE

Cursor IDE setup instructions

  • Go to Settings → Cursor Settings → Tools & MCP
  • Add the following configuration to mcp.json:

Online Authentication (Recommended)

1{
2  "mcpServers": {
3    ...
4    "evinced-mobile-mcp": {
5      "command": "npx",
6      "args": ["-y", "@evinced/mcp-server-mobile@latest"],
7      "env": {
8        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
9        "EVINCED_API_KEY": "YOUR_API_KEY"
10      }
11    }
12  }
13}

Offline Authentication

1{
2  "mcpServers": {
3    ...
4    "evinced-mobile-mcp": {
5      "command": "npx",
6      "args": ["-y", "@evinced/mcp-server-mobile@latest"],
7      "env": {
8        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
9        "EVINCED_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
10      }
11    }
12  }
13}

Verify Setup

Verify the evinced-mobile-mcp status is green on Cursor Settings → Tools & MCP tab.

Claude Code setup instructions

The MCP server may be installed using 2 different approaches:

  1. By running the following command in the terminal:

    Online Authentication (Recommended)

    1claude mcp add --transport stdio -e EVINCED_SERVICE_ACCOUNT_ID=YOUR_ACCOUNT_ID -e EVINCED_API_KEY=YOUR_API_KEY -- evinced-mobile-mcp npx -y @evinced/mcp-server-mobile@latest

    Offline Authentication

    1claude mcp add --transport stdio -e EVINCED_SERVICE_ACCOUNT_ID=YOUR_ACCOUNT_ID -e EVINCED_ACCESS_TOKEN=YOUR_ACCESS_TOKEN -- evinced-mobile-mcp npx -y @evinced/mcp-server-mobile@latest

  2. By adding a .mcp.json file with the following content to the project root:

    Online Authentication (Recommended)

    1{
    2  "mcpServers": {
    3    "evinced-mobile-mcp": {
    4      "type": "stdio",
    5      "command": "npx",
    6      "args": ["-y", "@evinced/mcp-server-mobile@latest"],
    7      "env": {
    8        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
    9        "EVINCED_API_KEY": "YOUR_API_KEY"
    10      }
    11    }
    12  }
    13}

    Offline Authentication

    1{
    2  "mcpServers": {
    3    "evinced-mobile-mcp": {
    4      "type": "stdio",
    5      "command": "npx",
    6      "args": ["-y", "@evinced/mcp-server-mobile@latest"],
    7      "env": {
    8        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
    9        "EVINCED_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
    10      }
    11    }
    12  }
    13}

Verify Setup

You can verify the setup in the following ways:

  1. By running the claude mcp get command:

    1claude mcp get evinced-mobile-mcp

    This should print the basic info about the evinced-mobile-mcp MCP installed, including the connection status.

  2. By running Claude Code with:

    1claude

    and then in the Claude Code console:

    1/mcp

    This will present the list of all the MCP servers currently installed. You can check the connection status of the evinced-mobile-mcp by navigating through the MCP menu.

More information on the MCP installation and the installation parameters can be found on the official Claude Code MCP documentation page.

Installation via Tarball (.tgz)

If your organization distributes Evinced Mobile MCP as a tarball (.tgz), install it locally and configure your IDE to run it.

  1. Install from tarball

    1npm i -g /absolute/path/to/evinced-mcp-server-mobile.tgz

  2. Configure Agent IDE

    Add the following configuration to mcp.json:

    Cursor IDE setup instructions

    1{
    2  "mcpServers": {
    3    "evinced-mobile-mcp": {
    4      "command": "evinced-mcp-server-mobile",
    5      "args": [],
    6      "env": {
    7        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
    8        "EVINCED_API_KEY": "YOUR_API_KEY"
    9      }
    10    }
    11  }
    12}

    Verify installation as described in the Cursor IDE setup section above.

    Claude Code setup instructions

    1{
    2  "mcpServers": {
    3    "evinced-mobile-mcp": {
    4      "type": "stdio",
    5      "command": "evinced-mcp-server-mobile",
    6      "args": [],
    7      "env": {
    8        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
    9        "EVINCED_API_KEY": "YOUR_API_KEY"
    10      }
    11    }
    12  }
    13}

    Verify installation as described in the Claude Code setup section above.

Configuration

Optionally, you can provide a configuration file to control which accessibility validations you want to run against your mobile app screen, as well as other configuration options.

To do so, save the config file in your file system and specify the absolute path to the file in the MCP config using the VALIDATION_CONFIG_PATH environment variable:

1{
2  "mcpServers": {
3    "evinced-mobile-mcp": {
4      "command": "npx",
5      "args": ["-y", "@evinced/mcp-server-mobile@latest"],
6      "env": {
7        "EVINCED_SERVICE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
8        "EVINCED_ACCESS_TOKEN": "YOUR_API_KEY",
9        "VALIDATION_CONFIG_PATH": "absolute/path/to/config_file"
10      }
11    }
12  }
13}

Below is a partial example of the config file:

1{
2  "accessibility": {
3    "rules": {
4      "conflictingStateInName": {
5        "enabled": false
6      },
7      "tappableArea": {
8        "options": {
9          "tappableAreaConformanceLevel": "AAA"
10        }
11      },
12      "duplicateName": {
13        "enabled": true,
14        "severity": "Minor"
15      }
16    }
17  }
18}

Usage

Evinced Mobile MCP can be used in various development and QA scenarios. Below are examples of possible user prompts:

Basic prompt:

1Analyze current screen for accessibility issues.

Involving device automation:

1Navigate to Settings -> User Details screen and analyze it for accessibility issues.

Full workflow example:

1Navigate to Settings -> User Details screen and analyze current screen for accessibility issues.
2

3// After issues are presented by agent
4Fix Critical and Serious issues

Additional Resources