Maestro MCP Server

Use Maestro's MCP server to let your coding agent write, run, and debug mobile and web UI tests.

Maestro implements the Model Context Protocol (MCP), enabling direct integration coding agents like Claude Code, Claude Desktop, Cursor, GitHub Copilot, Codex, Codex Desktop, Gemini, Windsurf, and JetBrains AI Assistant (full list). For more information on MCP see What is MCP?.

How to Install Maestro MCP

1

Prerequisites

• Install Maestro CLI
• Any coding agent that supports MCP (full list)

2

Install the Maestro MCP on your coding agent

Claude Code CLI

1. Install the Maestro CLI.
2. Run:

   claude mcp add maestro -- maestro mcp

See the Claude Code MCP docs for scope options (--scope user, --scope project, etc.).

Claude Desktop

1. Install the Maestro CLI.
2. In Claude Desktop, open Settings → Developer → Edit Config and merge the following into claude_desktop_config.json:

   {
       "mcpServers": {
           "maestro": {
               "command": "<full path to maestro binary>",
               "args": ["mcp"],
               "env": {
                   "JAVA_HOME": "<full JAVA_HOME directory>"
               }
           }
       }
   }

   The config file lives at:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   Claude Desktop launches from a minimal shell, so pass JAVA_HOME explicitly and use the full path to the maestro binary (run which maestro in your terminal to find it).

The Connectors UI in Claude Desktop only supports remote MCP servers that use OAuth. Local stdio servers like Maestro must be added by editing claude_desktop_config.json directly.

Codex CLI

1. Install the Maestro CLI.
2. Run:

   codex mcp add maestro -- maestro mcp

   Or add to ~/.codex/config.toml manually:

   [mcp_servers.maestro]
   command = "maestro"
   args = ["mcp"]

See the Codex MCP docs and the config reference.

Codex Desktop App

The Codex Desktop App shares its MCP config (~/.codex/config.toml) with the Codex CLI. If Maestro is already set up there, the Desktop App will pick it up automatically.

Otherwise:

1. Install the Maestro CLI.
2. In the Codex Desktop App, click the Settings button, then Settings again, and select MCP servers in the sidebar.
3. Click Add server and fill in the form:

   • Name: maestro
   • Type: STDIO
   • Command to launch: maestro
   • Arguments: mcp

   Then click Save.

See the Codex MCP docs and the config reference.

GitHub Copilot CLI

1. Install the Maestro CLI.
2. In a Copilot CLI session, run /mcp add and follow the interactive form with:

   • Name: maestro
   • Type: local
   • Command: maestro mcp

   Or add to ~/.copilot/mcp-config.json manually:

   {
       "mcpServers": {
           "maestro": {
               "type": "local",
               "command": "maestro",
               "args": ["mcp"]
           }
       }
   }

See the Copilot CLI MCP docs.

Cursor IDE

1. Install the Maestro CLI.
2. Install the MCP. The quickest option is the one-click button:

   

   Or set it up manually: open Cursor Settings → Tools & MCPs → Add Custom MCP. Cursor opens ~/.cursor/mcp.json for editing. Merge the following into it (or into a project-scoped .cursor/mcp.json in your repo root):

   {
       "mcpServers": {
           "maestro": {
               "command": "maestro",
               "args": ["mcp"]
           }
       }
   }

See the Cursor MCP docs for more.

Cursor CLI

The Cursor CLI shares its MCP config with the Cursor IDE. If Maestro is already set up in the IDE, there's nothing else to do.

Otherwise:

1. Install the Maestro CLI.
2. Add Maestro to .cursor/mcp.json in your project root:

   {
       "mcpServers": {
           "maestro": {
               "command": "maestro",
               "args": ["mcp"]
           }
       }
   }

See the Cursor CLI MCP docs.

Gemini CLI

1. Install the Maestro CLI.
2. Run:

   gemini mcp add maestro maestro mcp

   Or add to ~/.gemini/settings.json manually:

   {
       "mcpServers": {
           "maestro": {
               "command": "maestro",
               "args": ["mcp"]
           }
       }
   }

See the Gemini CLI MCP docs for scope options (-s user, -s project, etc.).

Other Coding Agents / Manual Installation

If your agent isn't listed above, the generic stdio config is:

{
    "mcpServers": {
        "maestro": {
            "command": "maestro",
            "args": ["mcp"]
        }
    }
}

This assumes maestro is on your PATH. If it isn't, replace "maestro" with the full path to the Maestro CLI executable (e.g. /opt/homebrew/bin/maestro).

If you run into PATH or JAVA_HOME issues, you can specify them explicitly:

{
    "mcpServers": {
        "maestro": {
            "command": "<full path to maestro binary>",
            "args": ["mcp"],
            "env": {
                "JAVA_HOME": "<full JAVA_HOME directory>"
            }
        }
    }
}

MCP documentation for other IDEs:

• Windsurf
• JetBrains IDEs
• VS Code

3

Restart and start building

Restart your coding agent, then let your agent handle checking its own work against a live mobile emulator or simulator. And when you're ready, generate repeatable end to end tests to ensure your feature doesn't break going forward.

How to Use the Maestro Viewer

Maestro MCP ships with Maestro Viewer - a web app that embeds an iOS simulator or Android emulator or physical device into your coding agent or browser. It shows the exact commands that Maestro MCP runs in real time, and enables full interactions with the embedded mobile device, allowing you to iterate end to end completely within the coding agent app of your choice.

The Maestro Viewer is exposed via the open_maestro_viewer MCP tool, so to open it simply ask your coding agent:

open the maestro viewer

Here's an example of the Maestro Viewer running in the embedded Cursor IDE browser:

How to Update Maestro MCP

The Maestro MCP is bundled inside the Maestro CLI, so upgrading the CLI upgrades the MCP server. After upgrading, your agent needs to reload the MCP connection to pick up the new binary.

1

Update the Maestro CLI

Maestro MCP ships as part of the Maestro CLI, so to update Maestro MCP:

• Update the Maestro CLI

2

Reload the Maestro MCP in your coding agent

Claude Code CLI

Run /mcp, select maestro, then Reconnect.

Claude Desktop

Restart Claude Desktop.

Codex CLI

Restart the Codex CLI.

Codex Desktop App

Restart the Codex Desktop App.

GitHub Copilot CLI

Restart the Copilot CLI.

Cursor IDE

Cursor Settings → Tools & MCPs and toggle the Maestro server off and on, or restart Cursor.

Cursor CLI

Restart cursor-agent. No in-session reload command exists.

Gemini CLI

Restart the Gemini CLI.

Other Coding Agents

Restart your coding agent.

MCP tools

Tool	Description
list_devices	List all available local devices (Android emulators, iOS simulators, and Chromium for web) that can be targeted for automation.
inspect_screen	Get the current screen's view hierarchy as compact JSON. Call this before targeting elements, and re-call after any UI change.
take_screenshot	Take a screenshot of the current device screen. Useful when a visual helps disambiguate elements.
run	Execute Maestro flows. Accepts exactly one of { yaml } (inline YAML, preferred for exploration), { files } (specific .yaml files), or { dir, include_tags, exclude_tags }. Syntax is validated as part of the call.
cheat_sheet	Return the Maestro cheat sheet covering common commands, flow syntax, and best practices. The agent should call this before authoring unfamiliar commands.
list_cloud_devices	List valid { device_model, device_os } pairs available on Maestro Cloud. Call before run_on_cloud. OS versions must be passed verbatim (e.g. iOS-17-5, android-34).
run_on_cloud	Submit a flow (or folder of flows) to Maestro Cloud. Returns upload_id, project_id, and a dashboard URL immediately.
get_cloud_run_status	Poll the status and per-flow results of a Cloud run. Poll every 60s until the status is terminal (SUCCESS, ERROR, CANCELED, WARNING).
open_maestro_viewer	Returns the running Viewer URL.

The list_cloud_devices, run_on_cloud, and get_cloud_run_status tools require Maestro Cloud authentication. Run maestro login (recommended) or set MAESTRO_CLOUD_API_KEY for non-interactive environments.

What is MCP?

The Model Context Protocol is an open standard that provides a uniform interface for connecting Large Language Models to external data sources, tools, and services. MCP defines a client-server architecture where:

• MCP Servers expose resources like data sources, APIs, and tools through a standardized interface.
• MCP Clients, such as AI apps, consume these resources via the protocol.
• Transport Layer handles communication using JSON-RPC 2.0 over stdio, HTTP with Server-Sent Events (SSE), or WebSocket connections.

The Maestro MCP server ships inside the Maestro CLI and exposes Maestro's authoring, device, and Cloud capabilities to your agent over stdio.