"Playwright MCP/Cursor Browser, but for Flutter apps"

Marionette MCP enables AI agents (Claude Code, Copilot, Cursor, Gemini CLI, and more) to inspect and interact with running Flutter applications. It connects your AI agent directly to a running app via the Model Context Protocol (MCP), so it can see the widget tree, tap elements, enter text, scroll, and capture screenshots for automated AI-driven smoke testing and interaction.

Marionette MCP keeps the surface area intentionally small. It exposes only a handful of high-signal actions and returns the minimum actionable data, which helps keep prompts focused and context sizes under control.

The official Dart & Flutter MCP server focuses on development-time tasks: searching pub.dev, managing dependencies, analyzing code, and inspecting runtime errors. It can also drive the UI, but it does so through Flutter Driver, which introduces extra instrumentation in your app. Marionette MCP focuses solely (and in an opinionated way) on runtime interaction: tapping buttons, entering text, scrolling, and taking screenshots, while requiring minimal changes to your app. Use Flutter MCP to build your app, use Marionette MCP to test and interact with it with minimal code changes.

1. Prepare your app — add marionette_flutter and initialize MarionetteBinding in main.dart:

   flutter pub add marionette_flutter

   void main() {
     if (kDebugMode) {
       MarionetteBinding.ensureInitialized();
     } else {
       WidgetsFlutterBinding.ensureInitialized();
     }
     runApp(const MyApp());
   }

2. Install the bridge — activate the MCP server (for the CLI alternative, see the CLI guide):

   dart pub global activate marionette_mcp

3. Configure your AI tool — e.g. for Claude Code:

   claude mcp add --transport stdio marionette -- marionette_mcp

   Other tools (Cursor, Gemini CLI, Copilot, Antigravity): see Configuring your AI tool.

4. Run your app in debug mode — flutter run, then copy the VM service URI from the console (e.g. ws://127.0.0.1:9101/ws).

5. Connect and interact — ask your agent to connect using that URI and start driving the app.

Once connected, an agent can drive your app with a small, focused toolset: inspect the widget tree (get_interactive_elements), tap / secondary_tap / double_tap / long_press / swipe / pinch_zoom / scroll_to, enter_text, press_back_button, take_screenshots, read get_logs, and hot_reload. Full list: MCP Tools.

Your app can also expose its own actions to the agent via Custom Extensions — navigate by route name, seed test data, toggle feature flags, and more.

Some real-world prompts:

"I implemented the Forgot Password screen — connect, navigate to login, tap 'Forgot Password', enter a valid email, submit, and check the logs that the API call fired."

"I refactored the routing. Run a smoke test: cycle through all bottom-nav tabs and verify each screen loads without exceptions in the logs."

"Investigate the unresponsive 'Clear Cache' button on Settings — find it via get_interactive_elements, tap it, and analyze the logs."

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

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