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.
Android emulator · Medium Phone API 36.1
✅ 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
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
Quick start
Three steps to the first prompt.
-
1
Add Marionette to the app
One package, and a binding that only exists in debug builds. Release builds stay untouched.
flutter pub add marionette_fluttervoid main() { if (kDebugMode) { MarionetteBinding.ensureInitialized(); } else { WidgetsFlutterBinding.ensureInitialized(); } runApp(const MyApp()); } -
2
Give your agent the tools
Pick the bridge you prefer: the MCP server or the
marionetteCLI. Both see and drive the app, and both write session reports. -
3
Run the app and ask
Paste the
ws://URI thatflutter runprints into the prompt. Or ask the agent to start the app: it reads the URI from the output itself.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.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.
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.
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
ispattern matches every subclass and every generic variant, such asDsSelect<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
loggingorloggerpackage, or from anything you route into aPrintLogCollector.
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_configsets 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
Install the skills →dart run skills@ getinstalls skills that teach the agent to set up your app, drive it well and turn a run into a Patrol test. -
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 →