Patrol MCP

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

Patrol promotional graphics

Learn more about Patrol:

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:

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.

Version Compatibility

For the version compatibility table between patrol_mcp and patrol_cli, see the Patrol MCP documentation.

Installation

Tip

AI-assisted setup: Ask your AI agent to install and configure Patrol MCP in this project. Paste the raw README into the conversation for full context.

Important

This README focuses on project-local MCP setup.

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).

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.
Add the config for your editor. The server is launched directly with dart run patrol_mcp — no wrapper script or chmod needed.

Most editors use the same entry — only the config file location differs. Add this block to your editor's MCP config file:

{
  "mcpServers": {
    "patrol": {
      "command": "dart",
      "args": ["run", "patrol_mcp"],
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

Editor	Config file	Notes
Claude Code	`.mcp.json` (project root)	Auto-discovered; you'll be prompted to approve on first use.
Cursor	`.cursor/mcp.json`	Enable MCP under Settings → Features → MCP.
Gemini CLI	`.gemini/settings.json`	`mcpServers` lives alongside other keys in this file.
Google Antigravity	Global — open via MCP store → Manage MCP Servers → View raw config	Per-workspace config isn't supported.
GitHub Copilot (CLI)	`.mcp.json` (project root), or `~/.copilot/mcp-config.json` (global)	Then run `/mcp` to confirm `patrol` is listed.

GitHub Copilot — VS Code extension (different format)

The VS Code extension uses .vscode/mcp.json with a servers key (not mcpServers) and an explicit "type": "stdio":

{
  "servers": {
    "patrol": {
      "type": "stdio",
      "command": "dart",
      "args": ["run", "patrol_mcp"],
      "env": {
        "PROJECT_ROOT": ".",
        "PATROL_FLAGS": "",
        "SHOW_TERMINAL": "false"
      }
    }
  }
}

See VS Code's MCP docs for starting the server.

Note

Upgrading from the run-patrol wrapper? It still works — you can delete the script and switch to the config above.

Note

Using FVM? If your project uses FVM, develop sessions use the pinned Flutter automatically. To override, set PATROL_FLUTTER_COMMAND in the env above. This auto-detects the develop Flutter, not the Dart that runs the server — so if dart run patrol_mcp fails with a version-resolution error under FVM, run the server under the pinned SDK too: "command": "fvm", "args": ["dart", "run", "patrol_mcp"].

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 --verbose. 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, which overrides FVM auto-detection).

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. Auto-selects a device (Android device > Android emulator > iOS device > iOS simulator), or pass device to target one; PATROL_FLAGS --device wins.
devices: Lists attached Android/iOS devices to pass as run's device.
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.

Agent skills

Patrol also ships agent skills that complement this MCP server — the MCP provides the tools above, while a skill teaches the agent how to use them to write Patrol tests. See the catalog for the list and install instructions.

Troubleshooting

Make sure your IDE is opened at the mobile project root.
Run dart pub get in the Flutter project root.
Confirm MCP server is enabled in your IDE settings.
Wrong Flutter/SDK used? The chosen Flutter command is logged to the server's stderr when a develop session starts (visible in your IDE's MCP logs).

🛠️ 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.

Need help with your Flutter project?

👉 Hire our team • Check our other packages