Skip to content
Back to search

marionette_mcp

MCP server enabling AI agents to interact with Flutter apps at runtime - let them inspect widgets, simulate taps, enter text, scroll, and take screenshots.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leancodepl--marionette-mcp/badge.svg)](/listings/leancodepl--marionette-mcp)

HTML

<a href="/listings/leancodepl--marionette-mcp"><img src="/api/listings/leancodepl--marionette-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> [!NOTE] > Your Flutter app must be prepared to be compatible with Marionette. The steps below are the short version — the [Getting Started guide](https://github.com/leancodepl/marionette_mcp/blob/main/docs/getting-started.md) walks through each one.

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](https://github.com/leancodepl/marionette_mcp/blob/main/docs/cli.md)):

   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](https://github.com/leancodepl/marionette_mcp/blob/main/docs/mcp-tools.md#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.

> [!IMPORTANT] > Standard Material widgets work out of the box. **If your app uses a custom design system, configuration is required** — otherwise the agent can't see or tap your custom buttons and fields. Start with the [Production Setup Checklist](https://github.com/leancodepl/marionette_mcp/blob/main/docs/configuration.md#production-setup-checklist).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 120 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <a href="https://marionette.leancode.co/?utm_source=github.com&utm_medium=referral&utm_campaign=marionette-mcp" align="center">
  2. <img alt="marionette_mcp" src="https://github.com/user-attachments/assets/12726942-57b3-4967-a1c8-bea06b397500" />
  3. </a>
  4. # Marionette MCP
  5. ![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
  6. [![marionette_mcp pub.dev badge](https://img.shields.io/pub/v/marionette_mcp)](https://pub.dev/packages/marionette_mcp)
  7. **Your agent's hands and eyes on a running Flutter app.**
  8. Marionette connects Claude Code, Cursor, Codex, Gemini CLI, Copilot or any MCP client to the Flutter app you run in debug mode. The agent sees the screen, taps, types, scrolls, reads the logs, hot reloads, and writes a report of what it did. If you know Playwright MCP: this is that, for Flutter.
  9. **[Website](https://marionette.leancode.co)** · **[Docs](https://marionette.leancode.co/docs/)** · [Video](https://youtu.be/JYsFDbKTJ54) · [Article](https://leancode.co/blog/marionette-mcp-in-flutter-apps?utm_source=github.com&utm_medium=referral&utm_campaign=marionette-readme)
  10. ## Quick start
  11. 1. Add the package to your app and initialize the binding in debug builds:
  12. ```bash
  13. flutter pub add marionette_flutter
  14. ```
  15. ```dart
  16. void main() {
  17. if (kDebugMode) {
  18. MarionetteBinding.ensureInitialized();
  19. } else {
  20. WidgetsFlutterBinding.ensureInitialized();
  21. }
  22. runApp(const MyApp());
  23. }
  24. ```
  25. 2. Give your agent a bridge: the MCP server or the `marionette` CLI, whichever you prefer ([every agent](https://marionette.leancode.co/docs/#bridge)):
  26. ```bash
  27. # MCP server, registered with Claude Code
  28. dart pub global activate marionette_mcp
  29. claude mcp add --transport stdio marionette -- marionette_mcp
  30. # or the CLI
  31. dart pub global activate marionette_cli
  32. ```
  33. 3. Run the app with `flutter run` and paste the `ws://…/ws` VM service URI it prints into the prompt, or ask the agent to run the app itself:
  34. > Connect to ws://127.0.0.1:9101/…/ws. On Profile, a malformed email must show an error and keep Submit disabled, and a valid one must submit.
  35. > [!IMPORTANT]
  36. > Flutter's own widgets work as is. **A custom design system needs one configuration step**, or the agent cannot see your buttons and fields: see [Configure](https://marionette.leancode.co/docs/configure/).
  37. ## What the agent can do
  38. | | Tools |
  39. | --- | --- |
  40. | **See** | `get_interactive_elements`, `take_screenshots` |
  41. | **Act** | `tap`, `enter_text`, `scroll_to`, `swipe`, `long_press`, `double_tap`, `pinch_zoom`, `press_key`, `press_back_button` |
  42. | **Verify** | `get_logs`, `set_device_config` (text scale, bold text, dark mode) |
  43. | **Iterate** | `hot_reload`, `hot_restart` |
  44. | **Extend** | your app's own actions, registered with `registerMarionetteExtension` |
  45. With `MarionetteConfiguration(enableSessionReports: true)`, every run leaves a folder: a `steps.md` the server writes, one line per tool call, and a `report.md` the agent writes from it. See [Reports](https://marionette.leancode.co/docs/reports/).
  46. The `marionette` CLI drives the app with the same actions as shell commands: see [Drive](https://marionette.leancode.co/docs/drive/#cli).
  47. ## Agent Skills
  48. `marionette_flutter` ships three [Agent Skills](https://github.com/leancodepl/marionette_mcp/tree/main/packages/marionette_flutter/skills):
  49. | Skill | Teaches the agent to |
  50. | --- | --- |
  51. | `marionette-flutter-setup` | Add the binding, configure a custom design system, logs and device config |
  52. | `marionette-flutter-drive-app` | Drive the app with the MCP tools or the CLI, and write the report |
  53. | `marionette-flutter-to-patrol` | Turn a verified run into Patrol tests |
  54. ```bash
  55. dart run skills@ get # in an app that depends on marionette_flutter
  56. npx skills add leancodepl/marionette_mcp # without the Dart toolchain
  57. ```
  58. ## Documentation
  59. | Page | What is inside |
  60. | --- | --- |
  61. | [Start](https://marionette.leancode.co/docs/) | Setup, every agent's config, the first prompt, the example app, FAQ |
  62. | [Concepts](https://marionette.leancode.co/docs/concepts/) | How the agent sees a screen, selectors, compaction, the single-binding rule |
  63. | [Configure](https://marionette.leancode.co/docs/configure/) | Custom design systems, Semantics, logs, device config, custom extensions |
  64. | [Drive](https://marionette.leancode.co/docs/drive/) | Prompts for common jobs, every tool with its CLI command, the CLI |
  65. | [Reports](https://marionette.leancode.co/docs/reports/) | Session folders, `steps.md`, `report.md`, the verdict |
  66. ## Packages
  67. | Package | Role |
  68. | --- | --- |
  69. | [`marionette_flutter`](https://pub.dev/packages/marionette_flutter) | The binding in your app. **Required.** |
  70. | [`marionette_mcp`](https://pub.dev/packages/marionette_mcp) | The MCP server your agent runs. |
  71. | [`marionette_cli`](https://pub.dev/packages/marionette_cli) | The `marionette` CLI, for shell-only agents. |
  72. | [`marionette_logging`](https://pub.dev/packages/marionette_logging) | Log collection from the `logging` package. |
  73. | [`marionette_logger`](https://pub.dev/packages/marionette_logger) | Log collection from the `logger` package. |
  74. ---
  75. ## 🛠️ Maintained by LeanCode
  76. <div align="center">
  77. <a href="https://leancode.co/?utm_source=github.com&utm_medium=referral&utm_campaign=marionette-mcp">
  78. <img src="https://leancodepublic.blob.core.windows.net/public/wide.png" alt="LeanCode Logo" height="100" />
  79. </a>
  80. </div>
  81. Marionette is built by **[LeanCode](https://leancode.co?utm_source=github.com&utm_medium=referral&utm_campaign=marionette-mcp)**, the creators of [Patrol](https://patrol.leancode.co/?utm_source=github.com&utm_medium=referral&utm_campaign=marionette-mcp), the testing framework for Flutter. We build Flutter products from scratch to long-term maintenance.
  82. <div align="center">
  83. [**👉 Hire our team**](https://leancode.co/get-estimate?utm_source=github.com&utm_medium=referral&utm_campaign=marionette-mcp)
  84. &nbsp;&nbsp;•&nbsp;&nbsp;
  85. [Check our other packages](https://pub.dev/packages?q=publisher%3Aleancode.co&sort=downloads)
  86. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.