minitap-mcp 0.3.0

Model Context Protocol server for controlling Android & iOS devices with natural language

Minitap MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to control and interact with real mobile devices (Android & iOS) through natural language commands.

Quick Start

Installation

pip install minitap-mcp

Prerequisites

Before running the MCP server, ensure you have the required mobile automation tools installed:

• For Android devices:

  • ADB (Android Debug Bridge) - For device communication
  • Maestro - For mobile automation (optional but recommended)

• For iOS devices (macOS only):

  • Xcode Command Line Tools with xcrun
  • Maestro - For mobile automation (optional but recommended)

For detailed setup instructions, see the mobile-use repository.

Configuration

Set your Minitap API credentials as environment variables:

export MINITAP_API_KEY="your_api_key_here"
export MINITAP_API_BASE_URL="https://platform.minitap.ai/api/v1"
export MINITAP_LLM_PROFILE_NAME="default"

You can set these variables in your .bashrc or equivalent.

Running the Server

With environment variables:

minitap-mcp --server

With API key as argument:

minitap-mcp --server --api-key your_api_key_here

Using --api-key overrides the MINITAP_API_KEY environment variable, useful for quick testing.

By default, the server will bind to 0.0.0.0:8000. Configure via environment variables:

export MCP_SERVER_HOST="0.0.0.0"
export MCP_SERVER_PORT="8000"

IDE Integration

1. Start the server: minitap-mcp --server
2. Add to your IDE MCP settings file:

# For Windsurf
{
  "mcpServers": {
    "minitap-mcp": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}

# For Cursor
{
  "mcpServers": {
    "minitap-mcp": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Available Tools

Once connected, your AI assistant can use these tools:

execute_mobile_command

Execute natural language commands on your mobile device using the Minitap SDK. This tool allows you to control your Android or iOS device using natural language.

Parameters:

• goal (required): High-level goal describing the action to perform
• output_description (optional): Description of expected output format
• profile (optional): Profile name to use (defaults to "default")

Examples:

"Open the settings app and tell me the battery level"
"Find the first 3 unread emails in Gmail"
"Open Google Maps and search for the nearest coffee shop"
"Take a screenshot and save it"

analyze_screen

Capture and analyze what's currently shown on the mobile device screen using a vision-capable LLM. Useful for understanding UI elements, extracting text, or identifying specific features.

Parameters:

• prompt (required): Analysis prompt describing what information to extract
• device_id (optional): Specific device ID to target

Examples:

"What app is currently open?"
"Read the text messages visible on screen"
"List all buttons and their labels on the current screen"
"Extract the phone number displayed"

Advanced Configuration

Custom ADB Server

If using a remote or custom ADB server (like on WSL):

export ADB_SERVER_SOCKET="tcp:192.168.1.100:5037"

Vision Model

Customize the vision model used for screen analysis:

export VISION_MODEL="qwen/qwen-2.5-vl-7b-instruct"

Device Setup

Android

1. Enable USB debugging on your device
2. Connect via USB or network ADB
3. Verify connection: adb devices

iOS (macOS only)

1. Install Xcode Command Line Tools
2. Start a simulator or connect a physical device
3. Verify: xcrun simctl list devices booted

Troubleshooting

No devices found:

• Verify ADB/xcrun connection
• Check USB debugging is enabled (Android)
• Ensure device is unlocked

Connection refused errors:

• Check ADB/xcrun connection

API authentication errors:

• Verify MINITAP_API_KEY is set correctly

Links

• Mobile-Use SDK: github.com/minitap-ai/mobile-use
• Mobile-Use Documentation: docs.minitap.ai