Mobile MCP Ai

🚀 Mobile MCP AI

A mobile automation MCP Server that provides mobile device control capabilities for Cursor AI, supporting Android/iOS.

🚀 Quick Start

1. Configure Cursor MCP

Edit ~/.cursor/mcp.json (macOS/Linux) or %APPDATA%\Cursor\mcp.json (Windows):

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

💡 Mode Switching (Optional):

• Default Full Version (39 Tools): Includes test script generation, operation history, dynamic configuration, etc. ⭐ Recommended
• Simplified Version (32 Tools): Add "env": {"MOBILE_MCP_MODE": "simple"}
  • ⚠️ The simplified version does not support test script generation (mobile_generate_test_script).
  • Suitable for scenarios that only require basic operations.

📝 Configuration Instructions:

• "cwd": The root directory of the project. Test scripts will be saved in the tests/ directory under this directory.
• AI Function: Cursor will automatically use the built-in AI without additional configuration.
• Other AI Platforms: Refer to the Configuration Guide when needed.

2. Connect Devices

# Android devices
adb devices  # Confirm that the device is visible

# iOS devices (Optional)
pip install mobile-mcp-ai[ios]

3. Restart Cursor

After the configuration is complete, completely exit and restart Cursor.

4. Start Using

Method 1: Basic Tools (Specify Elements Clearly)

@MCP Help me test the login:
1. List all elements.
2. Click the element with the resource-id "com.app:id/login_btn".
3. Enter "admin" in the resource-id "com.app:id/username".
4. Take a screenshot and save it.

Method 2: Let Cursor AI Analyze Screenshots (Recommended)

@MCP Help me test the login:
1. Take a screenshot to see the current page.
2. Analyze and click the "Login" button.
3. Enter "admin" in the "Username" input box.
4. Take a screenshot to confirm.

Cursor AI will automatically take screenshots, analyze the pictures, find the element coordinates, and perform operations!

✨ Features

🎯 Optional AI Functions

• Basic Mode: No need to configure an AI key. Cursor AI provides all intelligent capabilities.
• Intelligent Mode: Optionally configure an AI key, suitable for building an automated testing platform.
• Zero-Cost Start: The basic tools are completely free, no additional AI API fees are required.
• Flexible Selection: Freely choose whether to enable AI functions according to the usage scenario.

📦 Tool Features

• 39 Tools: Cover element operations, device management, test generation, etc.
• Operation Recording: Automatically record operations and generate pytest test scripts with one click.
• Dual-Platform Support: Unified interface for Android and iOS.
• Intelligent Verification: Automatically verify whether key operations take effect.

🤖 Deep Integration with Cursor AI

• MCP Protocol: Based on the Model Context Protocol, seamless integration.
• 39 Tools: Rich mobile operation tools (full version).
• Visual Recognition: Cursor AI can directly analyze screenshots and perform operations.
• Test Generation: Generate pytest scripts with one click after AI operations.

📦 Installation

Basic Installation (Recommended, Preferred for Cursor Users)

# Only includes core dependencies. Cursor AI provides all intelligent capabilities.
pip install mobile-mcp-ai

✅ Applicable Scenarios:

• Use in Cursor (most common).
• Use 32 basic tools.
• No need for an additional AI API key.

Complete Installation (Build an Automated Platform)

# Additionally install AI SDKs: Tongyi Qianwen, OpenAI, Claude
pip install mobile-mcp-ai[ai]

✅ Applicable Scenarios:

• Build an independent automated testing platform.
• Use intelligent tools in CI/CD.
• Need to run independently without Cursor.

💡 Difference Explanation: The basic version does not include AI SDKs such as dashscope, openai, and anthropic. It is fully sufficient when using in Cursor (Cursor AI provides intelligent capabilities). Only when you need to run intelligent tools in an independent environment do you need a complete installation.

Upgrade to the Latest Version

⚠️ Important: If you have installed an old version, it is strongly recommended to upgrade to v2.1.0!

# Upgrade to the latest version
pip install --upgrade mobile-mcp-ai

# Verify the version
pip show mobile-mcp-ai

💻 Usage Examples

Scenario 1: Basic Tool Testing (Specify Elements Clearly)

@MCP Perform the following operations:
1. Start the application com.example.app.
2. List all clickable elements.
3. Click the element with the resource-id "com.example:id/login_btn".
4. Wait for the element "com.example:id/home" to appear.
5. Take a screenshot and save it.

Scenario 2: Cursor AI Visual Analysis (Intelligent Recommendation)

@MCP Help me test the login function:
1. Take a screenshot to see the current page.
2. Find and click the "Login" button.
3. Take another screenshot, find the "Username" input box, and enter "test123".
4. Find the "Password" input box and enter "pass123".
5. Click the "OK" button.
6. Take a screenshot to confirm the result.

Scenario 3: Intelligent Tools (Need to Configure AI)

@MCP Check the AI function status.
@MCP Click the "Login" button in an intelligent way.
@MCP Enter "test123" in the "Username" input box.

Scenario 4: Generate Test Scripts (Recommended) ✨ New

@MCP Help me test the login function:
1. Start the application com.example.app.
2. Take a screenshot, find the "Login" button, and click it.
3. Enter "test123" in the "Username".
4. Enter "pass123" in the "Password".
5. Click the "Submit" button.

@MCP Generate a test script for the above operations.

AI will automatically generate a complete pytest test script:

• ✅ Save it to the tests/ directory of your project.
• ✅ Include intelligent waiting logic (page loading, jumping, input).
• ✅ Automatically handle pop-up windows (click if they exist, skip if they don't).
• ✅ Support multiple devices (automatically detect device IDs).
• ✅ Run independently (only need pip install uiautomator2 pytest).

Example of the generated script:

def test_登录(device):
    d = device
    
    # Step 1: Click "Login"
    d.click(540, 338)
    time.sleep(2.0)  # Intelligent waiting for page jump
    
    # Step 2: Enter the username
    d(resourceId="com.example:id/username").set_text("test123")
    time.sleep(1.5)
    
    # Step 3: Click Submit
    d.click(972, 1200)
    time.sleep(2.0)
    
    assert d(text="首页").exists()

🛠️ Tool List Overview

📊 Tool Classification Statistics

🔥 Quick Overview of Commonly Used Tools

Basic Operations (No AI Required)

• mobile_list_elements - List all interactive elements.
• mobile_click_by_id / mobile_click_by_text - Precise click.
• mobile_input_text_by_id - Input text.
• mobile_take_screenshot - Take a screenshot (for Cursor AI analysis).
• mobile_wait - Wait for a specified time or element ⭐ Exclusive to the full version.
• mobile_wait_for_element - Wait for an element to appear.

Intelligent Operations (Need AI, Optional)

• mobile_smart_click - Intelligent click with natural language.
• mobile_smart_input - Intelligent input with natural language.
• mobile_analyze_screenshot - AI visual analysis.
• mobile_execute_test_case - Intelligent test execution ⭐ Exclusive to the full version.
• mobile_generate_test_script - Generate pytest scripts ⭐ Exclusive to the full version.

Device and Application Management

• mobile_list_devices - List connected devices.
• mobile_launch_app - Start an application.
• mobile_list_apps - List installed applications.
• mobile_get_screen_size - Get the screen size.

Dynamic Configuration ⭐ Exclusive to the Full Version

• mobile_configure - Adjust waiting time, verification strategy, etc.
• mobile_get_config - View the current configuration.

📋 New Tools: Device connection management (check_connection, reconnect_device), operation history management (get_operation_history, clear_operation_history).

🔧 Technical Details

mobile_press_key - Completely Solve the "False Success" Problem

Problem Background: Traditional key operations only check whether the command is executed, without verifying whether the key actually takes effect, resulting in:

• ✗ Command execution success ≠ Key takes effect.
• ✗ The test shows passing, but the actual operation fails.
• ✗ The search key does not work in some applications/input methods.

Intelligent Verification Solution:

# Method 1: Verification Mode (Recommended, Default)
await press_key("search", verify=True)
# ✅ Automatically detect page changes.
# ✅ Automatically try the Enter key when the search key is invalid.
# ✅ Return the real operation result.

# Method 2: Quick Mode
await press_key("back", verify=False)
# ⚡ Return immediately after execution.
# ⚠️  Does not guarantee the key effect.

Working Principle:

1. Snapshot Before Operation - Record the current page state.
2. Execute Key - Send the key command.
3. Page Monitoring - Wait and detect page changes (up to 2 seconds).
4. Intelligent Judgment - Consider it successful if the page change is > 5%.
5. Search Key Fallback - Automatically try the Enter key when the SEARCH key is invalid.

Usage Example:

@MCP Help me search:
1. Enter "Test Content" in the search box.
2. Press the search key (automatically verify).

Return Result:

{
  "success": true,
  "key": "search",
  "keycode": 84,
  "verified": true,
  "page_changed": true,
  "fallback_used": false,
  "message": "The search key (SEARCH) takes effect."
}

If the SEARCH key is invalid:

{
  "success": true,
  "key": "search",
  "keycode": 66,
  "verified": true,
  "page_changed": true,
  "fallback_used": true,
  "message": "The search key (SEARCH) is invalid. The ENTER key has been used as a replacement and succeeded."
}

If the key is invalid:

{
  "success": false,
  "key": "search",
  "verified": true,
  "page_changed": false,
  "message": "The key command is executed successfully, but the page does not change. The key may not have taken effect."
}

Usage Recommendations:

Performance Comparison:

• Quick Mode: ~0.05 seconds (does not guarantee the effect).
• Verification Mode: ~0.5 - 2 seconds (ensure success).
• Additional Time Consumption: Less than 2 seconds, in exchange for reliability.

Supported Keys:

• enter / 回车 - Enter key (keycode=66).
• search / 搜索 - Search key (keycode=84, automatically fallback to 66).
• back / 返回 - Back key (keycode=4).
• home - Home key (keycode=3).
• Directly use the keycode number (e.g., 66).

Demo Script: Run python backend/mobile_mcp/examples/press_key_verification_demo.py to view the complete demo.

📚 Documentation

• User Configuration Guide - AI key configuration, common problems.
• Startup Guide - Complete installation and configuration steps.
• Test Script Generation - How to generate pytest test scripts.
• Automated Behavior Configuration Instructions - Control screen orientation and automatically close ads.

🆕 Changelog

v2.2.6 (Latest)

• ✅ Fix the screenshot directory path problem (fix the path calculation error).
• ✅ Fix the MCP package import conflict (delay the import to avoid conflicts with system packages).
• ✅ Improve the directory creation logic (use parents=True to ensure the creation of the parent directory).

v2.2.5

• ✅ Merge the dual servers into a unified architecture, and control the mode through environment variables.
• ✅ Add device connection management (check_connection, reconnect_device).
• ✅ Add operation history management (get_operation_history, clear_operation_history).
• ✅ Unify the return value format to standard JSON.
• ✅ Fix logical errors (device_info field, duplicate slicing, etc.).

View the complete log in CHANGELOG.md.

📊 Technology Stack

• MCP Protocol: Seamless integration with Cursor AI.
• UIAutomator2: Android automation engine.
• Appium: iOS automation support (optional).
• Multi-AI Support: Tongyi Qianwen, OpenAI, Claude (optional).

🤝 Contribution

Welcome to submit issues and pull requests!

If you have any questions or suggestions, please feel free to feedback in the issues.

📄 License

Apache License 2.0