Patrol MCP - New Approach to Patrol Testing with AI

We introduce Patrol MCP! A new way of working with Patrol by enabling AI agents to write, run, and debug E2E tests using patrol develop. By bridging the gap between AI and Patrol test execution, it significantly speeds up test development and unlocks a more autonomous testing workflow.

It’s our answer to what the Flutter community has been asking for - a way to connect AI directly with real Flutter E2E testing. And just like with earlier versions of Patrol, this release is rooted in real needs we’ve seen across teams: faster iteration, less manual work, and better feedback loops.

Patrol MCP is the next step in that journey. Watch it in action below and then continue reading. 😉

Giving AI visibility and control

AI agents are excellent at generating code, but in the context of Patrol testing, they are functionally blind. They cannot see what is happening on the device, they struggle with the slow execution of standard patrol test commands, and they lack the ability to use patrol develop.

Patrol MCP by LeanCode is designed to bridge this exact gap. It acts as a set of eyes and hands for your AI agent, allowing it to write Patrol tests, execute them, and observe what’s happening on the device in real time.

Why MCP?

The Model Context Protocol (MCP) standardizes how AI models connect to data sources and tools. By enhancing Patrol's testing capabilities with an MCP server, we enable AI agents to use develop mode. Instead of a developer manually running tests, taking screenshots, reading error logs, and pasting them into the prompt, the agent can directly control the entirety of that process.

Using MCP dramatically speeds up test development because it removes the constant back-and-forth between the developer and the AI, turning a slow, manual loop into a fast, automated one.

Until now, agents were unable to use patrol develop because its process never finishes - it runs in a loop awaiting user input (R - restart, Q - quit, etc.). Typically, when running commands, AI agents wait until the command finishes running. This blocks AI from using develop. 

At this point, we’ve decided to work around that by implementing the MCP server, which will recognize when the test finishes in develop mode. After the initial POC, the results were very promising - so we didn’t stop there.

What is Patrol MCP

Patrol MCP is a Dart-based MCP server that wraps patrol develop sessions. Developed as part of Patrol, it communicates with AI agents via standard input/output (stdio) transport. 

At its core, it is an orchestration layer. It manages a Patrol session, handling the testing lifecycle: starting, re-running, detecting completion, and cleaning up - all in a way that AI agents can reliably work with.

If you had a chance to use Marionette MCP by LeanCode, you might see how those two tools complement each other. Marionette MCP excels during the active development phase, allowing you to rapidly verify specific logic or UI components as you write them. However, since Marionette cannot interact with native system elements, it is best suited for these localized "in-app" checks. Patrol MCP focuses on writing E2E tests for new features and verifying that they pass, so you can deploy them and run them on CI.

It’s also worth highlighting why Patrol MCP matters even in a world where other MCP servers already exist. Most MCP implementations expose static data or simple commands. Patrol MCP goes further - it handles a long-running, interactive process (patrol develop) and turns it into something AI can actually control. That’s what makes it uniquely suited for testing mobile apps.

Features

Patrol MCP exposes 5 distinct tools to the AI agent:

• run: Executes a specified test file. It intelligently starts a new patrol develop session or, if the same test is already running, triggers a hot-restart by sending an R command
• screenshot: Captures the device's current state. It auto-detects Android (via adb) or iOS (via xcrun simctl) and automatically resizes the image to a height of 800 pixels to save tokens.
• native-tree: Fetches the native UI hierarchy (Android or iOS) directly from the running app. To prevent token bloat, the tree is heavily trimmed—stripping non-essential fields and flattening anonymous wrapper nodes to deliver only selector-relevant data (identifiers, labels, text).
• status: Returns the current session state, device information, and recent output (the last 200 lines). This is highly effective for autonomous AI debugging.
• quit: Gracefully stops the active testing session and cleans up resources.

How to use it

While you can use and interact with Patrol MCP however you want, we have found a few workflows particularly effective for collaborating with an AI.

The Step-by-Step Approach: We strongly advise telling your AI agent to write the test step-by-step, validating each step with a test run. This incremental approach allows the AI to capture a screenshot at the end of the last step, confirming the system's final state at the end of the test. AI works well when prompted with manual test case scenarios.

Automated Bug Fixing: If a test breaks, you no longer have to manually dig through logs. Simply ask the AI to fix it. Because the agent has access to the app code, there is a very good chance it will pinpoint the exact root cause. From there, your QA team can easily report the bug, or, if the app's behavior has intentionally changed, you can simply commit the updated test generated by the AI.

Patrol MCP & Automated Test Fixes With One Prompt in Antigravity

Setup and configuration

Getting Patrol MCP running involves preparing your Flutter repository and connecting it to your AI tool. 

Compatibility

Patrol MCP was tested with:

• Claude Code (CLI & VS Code extension),
• Cursor,
• Copilot,
• Gemini CLI,
• Google Antigravity,

and should work with all tools that support MCP servers.

Setup

To get started, first add the patrol_mcp package as a dev_dependency with dart pub add --dev patrol_mcp. Next, create an executable launcher script (typically named run-patrol) in your workspace to act as the MCP server's entry point. 

#!/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

Customize Patrol MCP behavior

You can customize the server’s behaviour by using environment variables within your MCP configuration (mcp.json):

• PATROL_FLAGS to pass patrol develop arguments (like flavors or ports)
• PROJECT_ROOT to define your working directory
• SHOW_TERMINAL for live log streaming in the terminal.

Example:

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

Registering the Server

Finally, you just need to register this launcher script as an MCP server within your AI assistant. Since the exact setup varies depending on whether you are using Cursor, Claude Code, Copilot, or Gemini CLI, check out the readme for the exact copy-paste configurations for your tool.

Limitations

Stability: The AI might occasionally get stuck during execution. Additionally, the experience is not currently great with iOS, as the patrol develop process tends to time out after 360 seconds.

Platform Constraints: We are currently focused on perfecting the mobile experience before expanding to other platforms. We plan to work on Flutter web support as soon as the bug that is blocking us is fixed.

Just like Patrol itself, it will continue to evolve based on real-world usage and feedback from the community on Discord. We’re actively listening to how teams use it and where it falls short - and we expect it to improve rapidly as more developers start experimenting with it.

Summary

Patrol MCP transforms AI assistants from functionally blind, code-only generators into full test developers.

By exposing device state (screenshots + native tree) and unlocking improved test execution (develop), it closes the feedback loop that AI agents need to write, run, view, and fix mobile Patrol tests end-to-end.

This is more than just an integration. It’s a new way of working with Patrol.

We’re especially excited to see how this changes everyday workflows for teams already using Patrol - and we hope all current Patrol users will give Patrol MCP a try and share their feedback with us.

Here you can find Patrol MCP!