Mobile MCP AI

Mobile MCP AI enables Cursor AI to control mobile devices for Android and iOS through a Model Context Protocol based MCP server. It provides a range of mobile automation tools, with optional AI capabilities, to streamline element interaction, recording, testing, and script generation across Android and iOS.

How to use

You run a local MCP server process and connect your MCP client (such as Cursor) to it. The server exposes a set of mobile automation tools that you can invoke from your MCP client. You can operate with explicit element actions or let Cursor AI analyze screenshots to identify and interact with elements. There are modes that determine how much AI assistance you want, from a fully autonomous setup to a minimal, core-tool workflow.

How to install

Prerequisites: you need Python and pip installed on your system. You also need Cursor (or another MCP client) to connect to the server.

# Basic installation (recommended for Cursor users)
pip install mobile-mcp-ai

# Full installation (for building an automated platform with AI SDKs)
pip install mobile-mcp-ai[ai]

Configuration and running the MCP server

Configure your MCP client to connect to the local MCP server. Use a local stdio server configuration that runs the server module as a Python process.

{
  "mcpServers": {
    "mobile_mcp_ai": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mobile_mcp.mcp.mcp_server"],
      "cwd": "/path/to/your/project"
    }
  }
}

Mode options and AI keys

There are two mode concepts you can select: the default full mode and a simplified mode. The simplified mode uses 32 basic tools and disables test script generation, making it lighter for straightforward automation tasks.

To enable simplified mode, add an environment setting in your client configuration: MOBILE_MCP_MODE with the value simple. This mode is useful when you only need core operations without test script generation.

Connecting devices and starting the server

1. Ensure your mobile device(s) are connected (Android via ADB; iOS via Appium if you use iOS features). 2) Start the MCP server using the command described earlier. 3) Launch Cursor and connect to the local MCP server you configured.

Usage patterns and examples

You can perform direct element interactions by explicitly selecting elements or by letting Cursor AI analyze screenshots and locate targets for you. Below are representative usage patterns you can translate into MCP client calls.

Practical examples

• Start an app, list interactable elements, click a login button by resource-id, enter a username, and take a screenshot for verification.

• Capture a screenshot of the current screen, let Cursor analyze it, and then perform the recommended actions (e.g., click the login button, fill in the username, and confirm the result with another screenshot).

Available tools

mobile_list_elements

List all interactive elements on the current screen.

mobile_click_by_id

Click an element by its resource-id or accessibility id.

mobile_click_by_text

Click an element by its visible text.

mobile_input_text_by_id

Input text into a field identified by id.

mobile_take_screenshot

Take a screenshot of the current screen for analysis by Cursor AI.

mobile_wait

Wait for a specified time or for an element to appear.

mobile_wait_for_element

Wait until a specific element appears on the screen.

mobile_smart_click

Click using AI-powered localization and context.

mobile_smart_input

Input text using AI-assisted understanding of the target field.

mobile_analyze_screenshot

AI-based visual analysis of the current screen.

mobile_execute_test_case

Smartly execute a prepared test case.

mobile_generate_test_script

Generate a pytest script from a recorded sequence of actions.

mobile_list_devices

List connected devices.

mobile_launch_app

Launch a specified application.

mobile_list_apps

List installed applications.

mobile_get_screen_size

Get the screen resolution of the device.

mobile_configure

Adjust dynamic configuration such as timeouts and verification policies (full version only).

mobile_get_config

Retrieve current configuration values (full version only).

check_connection

Check device connection status.

reconnect_device

Reconnect a previously connected device.

get_operation_history

Retrieve the operation history.

clear_operation_history

Clear the operation history.