Maestro MCP Setup Guide

Maestro MCP Setup Guide

Complete setup instructions for the Maestro MCP server. This guide covers the forked Maestro with gRPC fixes required for reliable Android emulator connectivity.

Overview

This guide uses a forked Maestro at olivier-motium/Maestro with critical fixes for MCP functionality:

These PRs are merged in the oli4-combined-fixes branch but NOT yet in upstream Maestro.

Prerequisites

1. Java 11+ - Required for building Maestro
2. Android SDK - With platform-tools for adb
3. Xcode - For iOS simulator (macOS only)
4. Git - For cloning the fork

Installation

Step 1: Clone the Forked Maestro

cd ~
git clone https://github.com/olivier-motium/Maestro.git maestro-fork
cd maestro-fork
git checkout oli4-combined-fixes

Step 2: Build Maestro CLI

./gradlew :maestro-cli:installDist

This creates the binary at:

maestro-cli/build/install/maestro/bin/maestro

Step 3: Configure MCP in Project

Add to your project's .mcp.json:

{
  "mcpServers": {
    "maestro-oli4-mcp": {
      "command": "/Users/YOUR_USERNAME/maestro-fork/maestro-cli/build/install/maestro/bin/maestro",
      "args": ["mcp"],
      "env": {}
    }
  }
}

IMPORTANT: Replace YOUR_USERNAME with your actual username.

Step 4: Restart Claude Code

The MCP server only loads on session start. After adding the config, restart Claude Code.

Android-Specific Setup

CRITICAL: Android emulators require additional manual setup that the MCP doesn't auto-provision.

Required: Install Maestro Driver APKs

Before using Maestro MCP with Android, install the driver packages:

# Set ADB path
ADB=$HOME/Library/Android/sdk/platform-tools/adb

# List connected devices
$ADB devices

# Install both driver APKs (from the built Maestro)
MAESTRO_DIR=~/maestro-fork
$ADB install -r $MAESTRO_DIR/maestro-client/build/resources/main/maestro-server.apk
$ADB install -r $MAESTRO_DIR/maestro-client/build/resources/main/maestro-app.apk

# Verify installation
$ADB shell pm list packages | grep maestro
# Should show: package:dev.mobile.maestro and package:dev.mobile.maestro.test

Required: Start Instrumentation Service

After installing APKs, start the driver service:

$ADB shell am instrument -w dev.mobile.maestro.test/androidx.test.runner.AndroidJUnitRunner &

Required: Set Up Port Forwarding

$ADB forward tcp:7001 tcp:7001

Convenience Script

Create a setup script for quick Android initialization:

#!/bin/bash
# save as: setup-maestro-android.sh

ADB=$HOME/Library/Android/sdk/platform-tools/adb
MAESTRO_DIR=~/maestro-fork

echo "Installing Maestro driver APKs..."
$ADB install -r $MAESTRO_DIR/maestro-client/build/resources/main/maestro-server.apk
$ADB install -r $MAESTRO_DIR/maestro-client/build/resources/main/maestro-app.apk

echo "Setting up port forwarding..."
$ADB forward tcp:7001 tcp:7001

echo "Starting instrumentation service..."
$ADB shell am instrument -w dev.mobile.maestro.test/androidx.test.runner.AndroidJUnitRunner &

sleep 3
echo "Maestro Android setup complete!"

iOS Setup

iOS simulators generally work out of the box. No additional setup required beyond having Xcode installed.

Verifying the Setup

1. Check MCP Tools Available

In Claude Code, use ToolSearch:

ToolSearch(query: "maestro")

Should return tools like:

• mcp__maestro-oli4-mcp__list_devices
• mcp__maestro-oli4-mcp__run_flow
• mcp__maestro-oli4-mcp__take_screenshot
• mcp__maestro-oli4-mcp__inspect_view_hierarchy

2. List Devices

mcp__maestro-oli4-mcp__list_devices()

Should show connected simulators/emulators with "connected": true.

3. Take Test Screenshot

mcp__maestro-oli4-mcp__take_screenshot(device_id: "emulator-5554")

Should return an image of the device screen.

Troubleshooting

Error: "UNAVAILABLE: io exception"

Cause: gRPC channel to Maestro driver failed.

Fix:

1. Check if driver APKs are installed: adb shell pm list packages | grep maestro
2. If not installed, follow "Install Maestro Driver APKs" above
3. Restart instrumentation service
4. Verify port forwarding is active

Error: "DEADLINE_EXCEEDED"

Cause: gRPC connection timed out waiting for driver.

Fix:

1. Ensure emulator is fully booted (not stuck on boot animation)
2. Re-run the full Android setup script
3. Try cold booting the emulator

Error: "No tools found" for Maestro

Cause: MCP server not connected.

Fix:

1. Verify .mcp.json has correct path to maestro binary
2. Ensure the binary exists and is executable
3. Restart Claude Code session
4. Check for errors in Claude Code startup logs

Error: "Failed to take screenshot" immediately after setup

Cause: Instrumentation service not fully started.

Fix: Wait 3-5 seconds after starting instrumentation, then retry.

Emulator shows in list but commands fail

Cause: Driver installed but port forwarding missing.

Fix:

$ADB forward tcp:7001 tcp:7001

Tool Reference

The actual MCP tool names (note the oli4 suffix):

Updating the Fork

To pull latest upstream changes and merge with fixes:

cd ~/maestro-fork
git fetch upstream
git checkout oli4-combined-fixes
git merge upstream/main
# Resolve conflicts if any
./gradlew :maestro-cli:installDist

Why a Fork?

The upstream Maestro MCP has issues connecting to Android emulators:

1. No driver auto-installation - The MCP assumes drivers are installed but doesn't install them
2. No gRPC retry - Connection failures are fatal instead of retried
3. No channel recreation - Once a gRPC channel fails, it stays dead

Our fork (PRs #2934 and #2935) addresses these issues. Until merged upstream, we use this fork.