Skip to content

v0.7.0Flutter 3.27+MCP + CLIApache-2.0

Your agent's hands and eyes on a running Flutter app.

If you know Playwright MCP, this is that for Flutter. Your coding agent connects to the app you run in debug mode, looks at the screen, taps, types, reads the logs and checks its own work, instead of guessing from the code.

flutter pub add marionette_flutter

You

Hot reload the app, then check the Profile form: a malformed email must show an error and keep Submit disabled, and a valid one must submit.

The agent drives the app through Marionette: 15 tool calls.

connecthot_reloadtapget_interactive_elementsenter_texttake_screenshotsget_logsdisconnect

Back to you

Marionette · Profile email validation — PASS: validation and submit work
✓ malformed email rejected, Submit disabled until the form is valid, form submits
→ .marionette/sessions/profile-email-validation-20261006T1326/report.md · 15 steps, 1 screenshot

One real run

Prompt in. Evidence out.

Recorded on the example app in this repository, driven through Marionette itself. Every tool call, screen and steps.md line below comes from that session.

agent
You Hot reload the app, then check the Profile form: a malformed email must show an error and keep Submit disabled, and a valid one must submit.
connect(uri: "ws://127.0.0.1:36383/…/ws", session_title: "profile email validation")
⎿ Successfully connected to app · Opened session: .marionette/sessions/profile-email-validation-20261006T1326
hot_reload()
⎿ Hot reload completed successfully
tap(text: "Profile")
⎿ Tapped element matching: {text: Profile}
get_interactive_elements()
⎿ Found 18 interactive element(s) · name_field, email_field, bio_field, FilledButton enabled: "false"
Three fields; the FilledButton (Submit) is disabled.
enter_text(key: "name_field", input: "Ada Lovelace")
⎿ Entered text into element matching: {key: name_field}
enter_text(key: "email_field", input: "ada@example")
⎿ Entered text into element matching: {key: email_field}
take_screenshots()
⎿ 1 screenshot, returned inline
The email field shows “Enter a valid email”.
get_interactive_elements()
⎿ Found 20 interactive element(s) · FilledButton enabled: "false"
Submit stays disabled.
enter_text(key: "email_field", input: "ada@example.com")
⎿ Entered text into element matching: {key: email_field}
enter_text(key: "bio_field", input: "Writes programs")
⎿ Entered text into element matching: {key: bio_field}
tap(text: "Submit")
⎿ Tapped element matching: {text: Submit}
get_interactive_elements()
⎿ Found 23 interactive element(s) · FilledButton enabled: "true", Text "Form submitted"
Submit is enabled and the “Form submitted” snackbar is on screen.
take_screenshots(inline: false)
⎿ Saved 1 screenshot(s): screenshots/01.png
get_logs()
⎿ No logs collected
Nothing logged, so no errors.
disconnect()
⎿ Successfully disconnected from app · Session: .marionette/sessions/profile-email-validation-20261006T1326 · Write report.md now.
Wrote report.md
The example app before the run The example app after connect(uri: "ws://127.0.0.1:36383/…/ws", session_title: "profile email validation") The example app after tap(text: "Profile") The example app after enter_text(key: "name_field", input: "Ada Lovelace") The example app after enter_text(key: "email_field", input: "ada@example") The example app after enter_text(key: "email_field", input: "ada@example.com") The example app after enter_text(key: "bio_field", input: "Writes programs") The example app after tap(text: "Submit")

Android emulator · Medium Phone API 36.1

.marionette/sessions/…/steps.md
- [13:26:45] connect uri=ws://127.0.0.1:36383 -> Successfully connected to app at ws://127.0.0.1:36383
- [13:26:47] hot_reload -> Hot reload completed successfully
- [13:26:47] tap text=Profile -> Tapped element matching: {text: Profile}
- [13:26:50] get_interactive_elements -> ok
- [13:26:50] enter_text key=name_field input_len=12 -> Entered text into element matching: {key: name_field}
- [13:26:52] enter_text key=email_field input_len=11 -> Entered text into element matching: {key: email_field}
- [13:26:55] take_screenshots -> 1 screenshot(s) captured
- [13:26:55] get_interactive_elements -> ok
- [13:26:56] enter_text key=email_field input_len=15 -> Entered text into element matching: {key: email_field}
- [13:26:58] enter_text key=bio_field input_len=15 -> Entered text into element matching: {key: bio_field}
- [13:27:00] tap text=Submit -> Tapped element matching: {text: Submit}
- [13:27:01] get_interactive_elements -> ok
- [13:27:02] take_screenshots -> Saved 1 screenshot(s): screenshots/01.png
- [13:27:02] get_logs -> ok
- [13:27:03] disconnect -> Successfully disconnected from app
report.md
✅ Marionette report — no issues · Profile email validation
Tested: hot reload, Profile form — name, malformed email, valid email, bio, submit (15 steps, 1 screenshot)
Checks: "ada@example" shows "Enter a valid email" and Submit stays disabled (steps 6–8); a valid email and a bio enable Submit, and submitting shows "Form submitted" (steps 9–12, screenshots/01.png); get_logs collected nothing, so no errors were logged (step 14)

What the agent can do

See. Act. Verify. Iterate.

A small set of tools, each returning only what the next decision needs, so the agent's context stays small.

  • See

    List every button, field and label on screen with its key, text and position, or take a screenshot.

    get_interactive_elementstake_screenshots

  • Act

    Tap, type, scroll, swipe, long-press, pinch and press keys, matched by key, Semantics identifier, text or type.

    tapenter_textscroll_toswipelong_presspress_keypress_back_button

  • Verify

    Read the app's logs to confirm the request fired or to catch the exception. Sweep text scale, bold text and dark mode.

    get_logsset_device_config

  • Iterate

    Change the code, hot reload, and replay the same steps to confirm the change.

    hot_reloadhot_restart

Session reports

Every run leaves a record you can check.

Turn on enableSessionReports and each run gets its own folder. The server logs every tool call. The agent writes the report and cites that log.

steps.mdwritten by the server

One line per tool call, appended as it happens. The agent cannot skip or embellish a step, and typed secrets are redacted.

report.mdwritten by the agent

Written at the end. Every finding cites a step, a log line or a screenshot, and the Tested: line is counted from steps.md, not from memory.

the verdictin the chat

One short closing message: what worked, what did not, what was not covered, and where the report is.

PASSSUSPECTFAILBLOCKED

.marionette/sessions/
profile-email-validation-20261006T1326/
  steps.md        # appended by the server, one line per call
  report.md       # written once, by the agent
  screenshots/
    01.png        # take_screenshots(inline: false)
    02.png

How a report is written, with examples →

Quick start

Three steps to the first prompt.

  1. 1

    Add Marionette to the app

    One package, and a binding that only exists in debug builds. Release builds stay untouched.

    terminal
    flutter pub add marionette_flutter
    lib/main.dart
    void main() {
      if (kDebugMode) {
        MarionetteBinding.ensureInitialized();
      } else {
        WidgetsFlutterBinding.ensureInitialized();
      }
      runApp(const MyApp());
    }
  2. 2

    Give your agent the tools

    Pick the bridge you prefer: the MCP server or the marionette CLI. Both see and drive the app, and both write session reports.

    MCP server

    Your agent calls Marionette’s tools.

    $ dart pub global activate marionette_mcp
    $ claude mcp add --transport stdio marionette -- marionette_mcp
    $ dart pub global activate marionette_mcp
    $ codex mcp add marionette -- marionette_mcp
    $ dart pub global activate marionette_mcp
    # then add to .cursor/mcp.json:
    { "mcpServers": { "marionette": { "command": "marionette_mcp", "args": [] } } }
    $ dart pub global activate marionette_mcp
    $ gemini mcp add marionette marionette_mcp
    $ dart pub global activate marionette_mcp
    $ copilot mcp add marionette -- marionette_mcp
    $ dart pub global activate marionette_mcp
    # then add to mcp_config.json:
    { "mcpServers": { "marionette": { "command": "marionette_mcp", "args": [] } } }

    CLI

    Your agent runs marionette commands in its shell.

    $ dart pub global activate marionette_cli
  3. 3

    Run the app and ask

    Paste the ws:// URI that flutter run prints into the prompt. Or ask the agent to start the app: it reads the URI from the output itself.

    prompt
    Connect to ws://127.0.0.1:9101/V3N5aBc=/ws. Open the login screen, sign in
    with test@example.com, and check the logs that the sign-in request fired.
    prompt
    Run the app with flutter run and connect to it. Open the login screen, sign
    in with test@example.com, and check the logs that the sign-in request fired.

    The full setup, step by step →

Your design system

Material works as is. Your widgets take one switch.

Marionette recognizes Flutter's own buttons, fields and controls with no configuration. For a custom design system, tell it which widgets are interactive and where their text lives.

example/lib/main.dart
MarionetteBinding.ensureInitialized(
  MarionetteConfiguration(
    isInteractiveElement: (element) => switch (element.widget) {
      DsButton() || DsSelect() => true,
      DsTile(:final onTap) => onTap != null,
      _ => false,
    },
    extractText: (element) => switch (element.widget) {
      DsSelect(:final selectedLabel) => selectedLabel,
      _ => null,
    },
  ),
);
  • An is pattern matches every subclass and every generic variant, such as DsSelect<T>.
  • Custom-painted content, such as a gauge or a chart, becomes readable through Semantics(label:, value:).
  • No key on a widget? Semantics(identifier:) is an equally stable selector, and screen readers never announce it.
  • Logs come from the logging or logger package, or from anything you route into a PrintLogCollector.

Configure your design system →

Beyond smoke tests

More than a test runner.

  • Reproduce, fix, replay

    Follow the steps from a ticket, fix the code, hot_reload, and replay the same steps. The agent shows the fix works instead of claiming it.

  • Accessibility sweeps

    set_device_config sets text scale, bold text and dark mode in the running app. The agent then reads the logs for overflow errors.

  • Your app's own tools

    Register an extension, such as “go to a page” or “seed test data”, and it becomes a named tool with a validated schema.

    Custom extensions →
  • MCP server or CLI

    Two bridges to the same app. Pick the one you and your agent prefer; both write the same session reports.

    Compare them →
  • Agent Skills in the package

    dart run skills@ get installs skills that teach the agent to set up your app, drive it well and turn a run into a Patrol test.

    Install the skills →
  • Evidence for a pull request

    Before and after screenshots, a session report, or a short video from marionette record-video.

Where it fits

Use it next to the tools you already have.

Build

Dart and Flutter MCP server

Searches pub.dev, manages dependencies, analyzes code and inspects runtime errors while the agent writes the app.

docs.flutter.dev →

Drive and verify

Marionette

Runs the app the agent just changed: looks at the screen, acts on it, reads the logs, and reports what it saw. Debug and profile builds.

How it works →

Regression suites

Patrol

Deterministic end-to-end tests for CI, which pass or fail the same way on every run. Marionette gestures simulate a user on a best-effort basis.

patrol.leancode.co →