maestro-mcp-tools-instructions

Instruction Command

When this command is used, acknowledge that you understand these instructions and will follow them throughout the conversation. Then await the user's request.

---

🔧 Maestro MCP Tools Guide

💡 Complete reference for using Maestro MCP (Model Context Protocol) tools in Claude Code.

Available MCP Tools

The Maestro MCP server provides the following tools for interacting with devices and running tests:

Device Management

list_devices

List all available devices (simulators/emulators) that can be used for automation.

// Usage
mcp__maestro__list_devices({})

// Returns list of devices with:
// - device_id: Unique identifier
// - platform: ios or android
// - name: Device name
// - status: booted, shutdown, etc.

start_device

Start a simulator/emulator and get its device ID.

// Start specific device
mcp__maestro__start_device({
  device_id: "device-uuid"
})

// Start any iOS device
mcp__maestro__start_device({
  platform: "ios"
})

// Start any Android device
mcp__maestro__start_device({
  platform: "android"
})

// Default (iOS)
mcp__maestro__start_device({})

App Control

launch_app

Launch an application on the connected device.

mcp__maestro__launch_app({
  device_id: "device-uuid",
  appId: "com.example.app"
})

stop_app

Stop an application on the connected device.

mcp__maestro__stop_app({
  device_id: "device-uuid",
  appId: "com.example.app"
})

UI Interaction

tap_on

Tap on a UI element by selector or description.

// Tap by text
mcp__maestro__tap_on({
  device_id: "device-uuid",
  text: "Sign In"
})

// Tap by ID
mcp__maestro__tap_on({
  device_id: "device-uuid",
  id: "signin_button"
})

// Tap with multiple criteria
mcp__maestro__tap_on({
  device_id: "device-uuid",
  text: "Submit",
  enabled: true,
  index: 0
})

// Fuzzy text matching (default: true)
mcp__maestro__tap_on({
  device_id: "device-uuid",
  text: "Sign",  // Will match "Sign In"
  use_fuzzy_matching: true
})