patrol_mcp 0.1.2

An MCP server that empowers AI assistants to control, automate, and monitor interactive Patrol development sessions in Flutter.

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

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

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:

Claude Code (CLI & VS Code extension)

Save the script to <workspace-root>/.claude/run-patrol and make it executable:

chmod +x .claude/run-patrol

Add to <workspace-root>/.mcp.json (must be at project root):

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

Claude Code automatically discovers .mcp.json from the project root — no additional registration step is needed. On first use, you will be prompted to approve the project-scoped MCP server.

Cursor

Save the script to <workspace-root>/.cursor/run-patrol and make it executable:

chmod +x .cursor/run-patrol

Add to <workspace-root>/.cursor/mcp.json:

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

Note

Make sure MCP is enabled in Cursor: Settings → Features → MCP.

Copilot

Save the script to <workspace-root>/.vscode/run-patrol and make it executable:

chmod +x .vscode/run-patrol

Add to <workspace-root>/.vscode/mcp.json:

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

Reload the IDE, then open Settings → MCP: List Servers. Go to Patrol and make sure the server is running — start it if needed.

Note

After editing mcp.json, you may need to restart the MCP server: Settings → MCP: List Servers → Patrol → Start.

Gemini CLI

Save the script to <workspace-root>/.gemini/run-patrol and make it executable:

chmod +x .gemini/run-patrol

Add to <workspace-root>/.gemini/settings.json:

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

Google Antigravity

Save the script to <workspace-root>/.antigravity/run-patrol and make it executable:

chmod +x .antigravity/run-patrol

Open the MCP store, click "Manage MCP Servers", then "View raw config" and add to mcp_config.json. Per-workspace MCP config is not yet supported — the config is global (~/.gemini/antigravity/mcp_config.json). The relative command path works because Antigravity resolves it against the open workspace:

{
  "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.

Need help with your Flutter project?

👉 Hire our team   •   Check our other packages