minitap-mcp 0.4.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

• For iOS devices (macOS only):

  • Xcode Command Line Tools with xcrun
  • Maestro - For mobile automation

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

Running the Server

The simplest way to start:

minitap-mcp --server --api-key your_minitap_api_key

This starts the server on localhost:8000 with your API key. Get your free API key at platform.minitap.ai/api-keys.

Available CLI options:

minitap-mcp --server --api-key YOUR_KEY --llm-profile PROFILE_NAME

• --api-key: Your Minitap API key (overrides MINITAP_API_KEY env var). Get yours at platform.minitap.ai/api-keys.
• --llm-profile: LLM profile name to use (overrides MINITAP_LLM_PROFILE_NAME env var). If unset, uses the default profile. Configure profiles at platform.minitap.ai/llm-profiles.

Configuration (Optional)

Alternatively, you can set environment variables instead of using CLI flags:

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

You can set these in your .bashrc or equivalent, then simply run:

minitap-mcp --server

CLI flags always override environment variables when both are present.

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 --api-key your_minitap_api_key
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): Natural language description of the desired output format. Results are returned as structured JSON (e.g., "An array with sender and subject for each email")
• 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