Patrol MCP

MCP server that lets AI agents run and manage Patrol tests in Flutter projects.

Learn more about Patrol:

• Our extensive documentation
• How Patrol 4.0 Makes Cross-Platform Flutter Testing Possible
• Simplifying Flutter Web Testing: Patrol Web
• Patrol VS Code Extension - A Better Way to Run and Debug Flutter UI Tests

How can we help you:

Patrol is an open-source framework created and maintained by LeanCode. However, if your company wants to scale fast and accelerate Patrol's adoption, we offer a set of value-added services on top of the core framework.

You can find out more below:

• 🚀 Automate Flutter app testing with Patrol
• 🚀 Patrol Setup & Patrol Training

Features

• Run Patrol tests and block until completion.
• Keep and reuse a develop session for hot-restart workflows.
• Stream logs and expose session status.
• Capture screenshots with auto-detected platform.
• Read native UI tree during active sessions.

Installation

By default, this setup assumes your Flutter project's pubspec.yaml is in the repository root. If your app lives in a subdirectory, set PROJECT_ROOT accordingly (for example ./app).

1. Add patrol_mcp as a dev dependency in your Flutter project:

   dart pub add --dev patrol_mcp
   

   Or add it manually to your pubspec.yaml with the latest version from pub.dev.

2. Create a launcher script named run-patrol with the contents below. Where to save it and how to configure MCP depends on your IDE — see step 3.

   #!/usr/bin/env sh
   set -e
   
   cd "${PROJECT_ROOT:-.}"
   export PROJECT_ROOT=$PWD
   
   if command -v fvm >/dev/null 2>&1; then
     export PATROL_FLUTTER_COMMAND="${PATROL_FLUTTER_COMMAND:-fvm flutter}"
     exec fvm dart run patrol_mcp
   else
     export PATROL_FLUTTER_COMMAND="${PATROL_FLUTTER_COMMAND:-flutter}"
     exec dart run patrol_mcp
   fi
   

3. Follow the instructions for your IDE:

chmod +x .claude/run-patrol

{
  "mcpServers": {
    "patrol": {
      "command": "./.claude/run-patrol",
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

chmod +x .cursor/run-patrol

{
  "mcpServers": {
    "patrol": {
      "command": "./.cursor/run-patrol",
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

chmod +x .vscode/run-patrol

{
  "servers": {
    "patrol": {
      "command": "./.vscode/run-patrol",
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

chmod +x .gemini/run-patrol

{
  "mcpServers": {
    "patrol": {
      "command": "./.gemini/run-patrol",
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

chmod +x .antigravity/run-patrol

{
  "mcpServers": {
    "patrol": {
      "command": "./.antigravity/run-patrol",
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

Environment Variables

• PROJECT_ROOT (recommended): Flutter project directory containing pubspec.yaml. If omitted, patrol_mcp uses the current working directory.
• PATROL_FLAGS: Extra patrol develop flags, for example: --flavor dev --no-uninstall --open-devtools. Use this for ports too: --test-server-port 8081 --app-server-port 8082.
• SHOW_TERMINAL: Open macOS Terminal for live logs ("true" / "false").

patrol_mcp also respects environment variables supported by patrol_cli (for example: PATROL_FLUTTER_COMMAND). The provided run-patrol script sets PATROL_FLUTTER_COMMAND automatically: fvm flutter when FVM is available, otherwise flutter.

Setup Best Practices

• Prefer local/project MCP config when sharing setup with a team.
• Keep MCP config in the repository so teammates share the same setup.

Tools

• run: Runs a test file and waits for completion.
• quit: Gracefully stops the active session.
• status: Returns session state and recent output.
• screenshot: Captures screenshot from active session device.
• native-tree: Fetches native UI tree from active session device.

Troubleshooting

• Make sure your IDE is opened at the mobile project root.
• Run dart pub get in the Flutter project root.
• Verify your configured run-patrol path is executable.
• Confirm MCP server is enabled in your IDE settings.

🛠️ Maintained by LeanCode

This package is built with 💙 by LeanCode. We are top-tier experts focused on Flutter Enterprise solutions.

Why LeanCode?

• Creators of Patrol - the next-gen testing framework for Flutter.
• Production-Ready - We use this package in apps with millions of users.
• Full-Cycle Product Development - We take your product from scratch to long-term maintenance.