Flutter Maestro

Experimental Model Context Protocol (MCP) server that enables AI agents to interact with running Flutter applications via the VM Service and execute Maestro flows. Just for playing around with custom MCPs

Prerequisites

• Maestro CLI: Required for running Maestro flows with the run_maestro_flow tool.
  • Install via Homebrew: brew install maestro
  • Or follow the official installation guide

Installation

1. Clone this repository.
2. Run dart pub get to install dependencies.

Configuration

VS Code

Add the following to your MCP settings file (typically ~/.vscode/mcp.json or similar, depending on the extension):

{
  "servers": {
    "flutter-maestro": {
      "command": "dart",
      "args": [
        "/absolute/path/to/flutter_maestro_mcp/bin/flutter_maestro_mcp.dart"
      ]
    }
  }
}

Note: Replace /absolute/path/to/flutter_maestro_mcp with the actual path to your cloned repository.

Testing with Example App

This repository includes an example Flutter application instrumented with test hooks to verify the MCP server functionality.

Using VS Code (Recommended):

1. Open the repository in VS Code.
2. Go to Run and Debug and select "Flutter Example App".
3. Copy the VM Service URI from the Debug Console.

Using Command Line:

1. Navigate to example/.
2. Run the app: flutter run.
3. Note the VM Service URI from the output (e.g., ws://127.0.0.1:12345/ws).

Once Running:

1. Copy the complete VM Service URI from the Flutter app output
2. Use the connect tool with this URI
3. Try tools like inspect_ui and tap to interact with the running example app

Finding the VM Service URI:

The VM Service URI is printed when your Flutter app starts. You MUST copy the complete URI including the authentication token:

• VS Code Debug Console: Search for "VM Service" or "Observatory"
• Flutter CLI output: Look for "The Dart VM service is listening on ws://..."
• URI format: ws://127.0.0.1:PORT/AUTH_TOKEN/ws
• Example: ws://127.0.0.1:59548/-ppep2G-MyI=/ws

⚠️ Important: Auto-discovery is not supported. You must provide the complete URI with the authentication token. The token is only printed once at app startup and cannot be retrieved later.

Available Tools

• connect: Connect to a running Flutter app using its VM Service URI.
  • Arguments: uri (required - the complete VM Service WebSocket URI including auth token from your Flutter app output, e.g., ws://127.0.0.1:59548/-ppep2G-MyI=/ws)
• disconnect: Disconnect from the current Flutter app.
• inspect_ui: Get a simplified JSON representation of the current UI hierarchy (keys, text, semantics).
• tap: Tap on a widget matching criteria.
  • Arguments: key, text, tooltip, semantics
• enter_text: Enter text into a widget matching criteria.
  • Arguments: input (required), plus matcher arguments (key, text, etc.)
• scroll_to: Scroll until a widget is visible.
  • Arguments: Matcher arguments (key, text, etc.)
• take_screenshot: Take a screenshot of the current screen.
• get_logs: Retrieve application logs.
• hot_reload: Trigger a hot reload.
• write_maestro_flow: Write a Maestro YAML flow to a file.
  • Arguments: path, content
• run_maestro_flow: Run a Maestro YAML flow using maestro test.
  • Arguments: path