MCP Maestro Mobile AI

AI-Assisted Mobile Automation using Model Context Protocol

An MCP (Model Context Protocol) server that enables AI assistants like Claude, Copilot, and other LLMs to run mobile automation tests using Maestro. Features app context training for improved test generation accuracy.

📚 Documentation

| Document | Description | |----------|-------------| | Enterprise Readiness | Architecture, security model, compliance | | Security Model | Execution boundaries, threat model, best practices | | Privacy Policy | Data handling, no telemetry statement | | Changelog | Version history, release notes | | Roadmap | Future plans, feature timeline | | Contributing | How to contribute |

🎯 What This Does

Testers write simple prompts → AI generates and runs tests automatically

# prompts/my-tests.txt
Test that user can login with valid credentials
Test that search shows results for "TechGuru"
Test that user can logout successfully

You: "Run tests from prompts/my-tests.txt"

AI: Reading prompts... Found 3 tests.
    [1/3] Generating login test... ✅ PASSED
    [2/3] Generating search test... ✅ PASSED
    [3/3] Generating logout test... ❌ FAILED

    Results: 2 passed, 1 failed

🚀 Installation Options

Prerequisites (Required for all methods)

• Node.js 18+
• Java 17+ (for Maestro)
• Maestro CLI installed (Installation Guide)
• Android Emulator or physical device connected via USB
• Cursor, Claude Desktop, or VS Code with GitHub Copilot

📦 Option 1: NPX (Zero Install - Recommended)

Run directly without installing:

npx mcp-maestro-mobile-ai

Then configure your AI client (see MCP Configuration below).

📦 Option 2: Global Install via NPM

# Install globally
npm install -g mcp-maestro-mobile-ai

# Run the server
maestro-mcp

📦 Option 3: Clone from GitHub

# 1. Clone the repository
git clone https://github.com/krunal-mahera/mcp-maestro-mobile-ai.git
cd mcp-maestro-mobile-ai

# 2. Install dependencies
npm install

# 3. Run the server
npm start

⚙️ MCP Configuration

Configure your AI client to use the Maestro MCP server.

🔧 Cursor Setup

Step 1: Locate Config File

| OS | Config File Location | | ----------- | -------------------------------- | | Windows | %USERPROFILE%\.cursor\mcp.json | | macOS | ~/.cursor/mcp.json | | Linux | ~/.cursor/mcp.json |

Step 2: Add Configuration

If installed via NPM (global):

{
  "mcpServers": {
    "maestro": {
      "command": "maestro-mcp",
      "env": {
        "APP_ID": "com.your.app.package"
      }
    }
  }
}

If using NPX (no install):

{
  "mcpServers": {
    "maestro": {
      "command": "npx",
      "args": ["mcp-maestro-mobile-ai"],
      "env": {
        "APP_ID": "com.your.app.package"
      }
    }
  }
}

If cloned from GitHub:

{
  "mcpServers": {
    "maestro": {
      "command": "node",
      "args": ["/path/to/mcp-maestro-mobile-ai/src/mcp-server/index.js"],
      "env": {
        "APP_ID": "com.your.app.package"
      }
    }
  }
}

Step 3: Restart Cursor

Close and reopen Cursor completely for the changes to take effect.

Step 4: Verify

In Cursor's AI chat, type:

List the available MCP tools for maestro

🔧 Claude Desktop Setup

Edit ~/.claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "maestro": {
      "command": "npx",
      "args": ["mcp-maestro-mobile-ai"],
      "env": {
        "APP_ID": "com.your.app.package"
      }
    }
  }
}

🔧 VS Code with GitHub Copilot

Add to VS Code settings (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):

{
  "github.copilot.chat.mcpServers": {
    "maestro": {
      "command": "npx",
      "args": ["mcp-maestro-mobile-ai"],
      "env": {
        "APP_ID": "com.your.app.package"
      }
    }
  }
}

📝 Note: GitHub Copilot MCP support may vary by version.

✅ Verify Your Setup

Test 1: Check Configuration

Ask the AI:

Get the maestro app configuration

Expected response:

{
  "success": true,
  "config": {
    "appId": "com.google.android.youtube",
    "platform": "android"
  }
}

Test 2: List Prompt Files

Ask the AI:

List available prompt files in the maestro server

Test 3: Run a Simple Test

Make sure your Android emulator is running, then ask:

Run a test: Open YouTube and search for TechGuru

📝 Usage Guide

For Testers - Creating Test Prompts

1. Create a prompt file in the prompts/ folder:

# prompts/my-app-tests.txt

# Login Tests
Test that user can login with valid email and password
Test that login fails with incorrect password
Test that forgot password link works

# Dashboard Tests
Test that dashboard shows user name after login
Test that notifications icon is visible

2. Ask the AI to run:

Run tests from prompts/my-app-tests.txt

3. AI handles everything:
   • ✅ Reads prompts
   • ✅ Generates Maestro YAML
   • ✅ Validates YAML
   • ✅ Runs tests on emulator
   • ✅ Reports results

🧠 App Context Training (NEW!)

The AI might not know your app's exact UI elements. Train it by registering your app's elements for much better test generation:

Step 1: Register UI Elements

Tell the AI:

Register these elements for app "com.myapp":
{
  "usernameInput": {
    "testId": "login-username-input",
    "accessibilityLabel": "Username",
    "type": "textfield"
  },
  "passwordInput": {
    "testId": "login-password-input", 
    "accessibilityLabel": "Password",
    "type": "textfield"
  },
  "loginButton": {
    "testId": "login-submit-btn",
    "text": "Sign In",
    "type": "button"
  }
}

Step 2: Register Screens (Optional)

Register screen "LoginScreen" for app "com.myapp" with:
- description: "Main login screen with email and password"
- elements: ["usernameInput", "passwordInput", "loginButton"]
- actions: ["login", "forgotPassword", "signUp"]

Step 3: Save Successful Flows

After a test passes, save it as a pattern:

Save this successful flow for "com.myapp" as "login-flow"

The AI will use this pattern for similar tests in the future!

Step 4: Get Context Before Tests

Always get context before generating tests:

Get AI context for app "com.myapp", then run a login test

This gives the AI all the element names and patterns it needs.

Tips for Writing Good Prompts

✅ Good prompts:

Test that user can login with valid email "[email protected]" and password "Test123"
Test that search results show products matching "shoes"
Test that error message appears when password is less than 6 characters
Test that user can navigate from home screen to settings

❌ Bad prompts:

Test login          (too vague)
Click button        (not a test case)
Check the app       (unclear expectation)

🔧 Available MCP Tools (14 Tools)

Prompt Tools

| Tool | Description | | ------------------- | -------------------------------------- | | read_prompt_file | Read test prompts from a .txt/.md file | | list_prompt_files | List available prompt files |

Device Management Tools

| Tool | Description | | --------------- | --------------------------------------------- | | list_devices | List all connected Android devices/emulators | | select_device | Select a specific device for test execution | | clear_device | Clear device selection (use first available) | | check_device | Check if Android emulator/device is connected | | check_app | Verify app is installed on device |

Test Execution Tools

| Tool | Description | | ----------------------- | ------------------------------------------- | | validate_maestro_yaml | Validate Maestro YAML syntax | | run_test | Run a single test (with auto-retry support) | | run_test_suite | Run multiple tests in sequence |

Configuration & Utility Tools

| Tool | Description | | ------------------ | ---------------------------------- | | get_app_config | Get app configuration and settings | | get_test_results | Get results from last run | | take_screenshot | Capture device screen | | cleanup_results | Clean up old test results |

📁 Project Structure

maestro-mcp-server/
├── prompts/                      # ⭐ TESTERS CREATE FILES HERE
│   ├── example-login-tests.txt
│   └── example-youtube-tests.txt
│
├── src/mcp-server/               # MCP Server (don't modify)
│   ├── index.js
│   ├── tools/
│   └── utils/
│
├── output/                       # Test outputs
│   ├── logs/
│   ├── screenshots/
│   └── results/
│
├── config/
│   └── maestro.config.yaml
│
├── docs/
│   ├── MCP_SETUP.md
│   └── REACT_NATIVE_AUTOMATION_GUIDELINES.md
│
├── mcp-config-cursor.json        # Ready-to-use Cursor config
├── mcp-config-vscode.json        # Ready-to-use VS Code config
├── env.example
├── package.json
└── README.md

⚙️ Environment Configuration

Required Variables

| Variable | Description | Example | | -------- | --------------------------- | ---------------------------- | | APP_ID | Package name of app to test | com.google.android.youtube |

Test Execution Settings

| Variable | Description | Default | | ---------------------- | --------------------------------------- | ------- | | DEFAULT_WAIT_TIMEOUT | Default wait timeout in ms | 10000 | | DEFAULT_RETRIES | Auto-retry count for failed tests | 1 | | MAX_RESULTS | Max result files to keep (auto-cleanup) | 50 |

Optional Variables

| Variable | Description | Default | | --------------- | ------------------- | ---------------- | | ANDROID_HOME | Path to Android SDK | Auto-detected | | EMULATOR_NAME | Preferred emulator | Default emulator | | PLATFORM | Target platform | android | | LOG_LEVEL | Logging level | info |

✨ New Features (v2.1.0)

🔌 Device Check

Before running tests, verify your device is connected:

Check if my device is connected

📱 App Check

Verify the app is installed before testing:

Check if YouTube app is installed

🔄 Auto-Retry

Failed tests are automatically retried based on DEFAULT_RETRIES setting:

• Set DEFAULT_RETRIES=2 to retry failed tests twice
• Reduces flaky test failures

🧹 Result Cleanup

Old results are automatically cleaned up:

• Keeps last 50 results by default (configurable via MAX_RESULTS)
• Use cleanup_results tool for manual cleanup

💬 Improved Error Messages

Errors now include:

• Clear descriptions of what went wrong
• Hints for how to fix the issue
• Automatic screenshots on failure

🔍 Troubleshooting

"Tools not appearing in Cursor/VS Code"

1. Verify the path in your MCP config is correct
2. Restart your editor completely
3. Check output/logs/mcp-server.log for errors

"APP_ID not configured"

Set APP_ID in either:

• The MCP config's env section, OR
• A .env file in the project root

"No emulator connected"

1. Start Android emulator from Android Studio
2. Verify with: adb devices

"Element not found" during test

The AI-generated selector might not match. Ask the AI to:

• Use different selectors (text-based instead of ID-based)
• Add more wait time with extendedWaitUntil
• Use maestro studio to inspect elements

"Java version error"

Maestro requires Java 17+. Check with:

java -version

🧪 Example Session

You: List the prompt files

AI: 📂 Found 2 prompt files:
    - example-login-tests.txt (5 prompts)
    - example-youtube-tests.txt (4 prompts)

You: Run tests from prompts/example-youtube-tests.txt

AI: 📂 Reading prompts...
    Found 4 test prompts.

    [1/4] "Test that user can open YouTube and search for TechGuru"
          🔧 Generating Maestro YAML...
          ✓ Validating YAML...
          🚀 Running test...
          ✅ PASSED (3.2s)

    [2/4] "Test that user can play the first video"
          🔧 Generating Maestro YAML...
          ✓ Validating YAML...
          🚀 Running test...
          ✅ PASSED (5.1s)

    [3/4] "Test that user can pause and resume"
          🔧 Generating Maestro YAML...
          ✓ Validating YAML...
          🚀 Running test...
          ✅ PASSED (4.3s)

    [4/4] "Test that user can subscribe"
          🔧 Generating Maestro YAML...
          ✓ Validating YAML...
          🚀 Running test...
          ❌ FAILED (2.1s)
          📸 Screenshot saved

    ━━━━━━━━━━━━━━━━━━━━━━━━━━━
    📊 Results: 3 passed, 1 failed
    📄 Report: output/results/latest.json
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━

You: What failed in test 4?

AI: Test 4 failed because the "Subscribe" button was not found.
    The screenshot shows the video is still loading.

    Would you like me to retry with more wait time?

📚 Additional Resources

• Maestro Documentation
• Model Context Protocol
• React Native Automation Guidelines
• MCP Setup Guide

🤝 For Other Projects

To use this MCP server with a different app:

1. Update APP_ID in your MCP config or .env file
2. Create new prompt files in prompts/ folder specific to your app
3. The AI will generate tests based on your app's UI

📦 Publishing to NPM (For Maintainers)

To publish this package to npm:

1. Update Package Name

Edit package.json and set your own npm scope:

{
  "name": "@your-org/maestro-mcp",
  "version": "1.0.0"
}

2. Login to NPM

npm login

3. Publish

# First time (create new package)
npm publish --access public

# Updates
npm version patch  # or minor, major
npm publish

4. Users Can Then Install Via

# Global install
npm install -g @your-org/maestro-mcp

# Or run directly
npx @your-org/maestro-mcp

🌟 GitHub Repository Setup

Recommended Repository Structure

your-org/maestro-mcp
├── .github/
│   ├── workflows/
│   │   ├── publish.yml       # Auto-publish to npm on release
│   │   └── test.yml          # CI tests
│   └── ISSUE_TEMPLATE/
├── src/
├── prompts/
├── README.md
├── LICENSE
└── package.json

GitHub Actions: Auto-Publish to NPM

Create .github/workflows/publish.yml:

name: Publish to NPM

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Then add NPM_TOKEN secret in your GitHub repository settings.

📜 License

MIT License