Marionette MCP: an agent inside a Flutter app
Marionette MCP
An MCP server for Flutter: the agent connects to a running app, reads the widget tree, taps, types, scrolls and takes screenshots
- 497 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The agent taps elements and types into a running app, so it can trigger any interface action on test data
- Screenshots and logs of the running app enter the model context
Install
- Works in
Manual install
dart pub global activate marionette_mcpInstalls the bridge. Prepare the app first: flutter pub add marionette_flutter and MarionetteBinding.ensureInitialized() in main.dart.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent taps elements and types into a running app, so it can trigger any interface action on test data
- Screenshots and logs of the running app enter the model context
This is third-party code. Review the repository files before installing.
What it does
Marionette connects an agent to a running Flutter app through the VM service. The author calls it the Playwright MCP for Flutter. The agent receives a list of interactive widgets with type, text, key and semantics identifier, and then acts: taps, double-taps, long-presses, swipes, pinch-zooms and scrolls to a target element. There are few tools, and each returns the minimum data to keep the context small. They are connect, disconnect, get_interactive_elements, take_screenshots, get_logs and the gestures tap, secondary_tap, double_tap, long_press, swipe, pinch_zoom, press_back_button and scroll_to. Screenshots arrive as PNG, and logs are gathered by LogCollector. Setup takes two steps. Add the marionette_flutter package to the app and call MarionetteBinding.ensureInitialized() in debug mode, then install the bridge with dart pub global activate marionette_mcp. A CLI variant of the same bridge exists.
Who it is for. For Flutter developers and testers who want Claude Code, Cursor, Copilot or Gemini CLI to walk through scenarios in a running app.
Good fit when
- You want to check an app screen live: what is visible, which elements respond and how swipes behave
- An agent has to walk a scenario on an emulator or device and show screenshots of each step
- Repeated keys in a grid of cards are separated with the ancestor_keys parameter, which limits the search to a subtree
- You need logs of a running app since the last hot reload through get_logs
- You want the agent to keep a report of a run with evidence: Marionette has session reports
Not a fit when
- You need pub.dev search, code analysis and dependency management: the official Dart and Flutter server does that
- The app is not built with Flutter: the server works through the Flutter VM service
- The app is built in release mode: the Marionette binding is enabled only in debug mode
- The project cannot take code changes: the app first has to be prepared with the package and an initializer
Example request
Run my Flutter app in debug mode, connect through Marionette, walk the sign-in screen and take a screenshot after each stepMCP
- Transport
- stdio
- Authentication
- not required
Limitations
- The app has to be prepared: add marionette_flutter and initialize the binding in main.dart. The author's example does this only under kDebugMode.
- Before any other tool the agent calls connect with the VM service address, for example ws://127.0.0.1:9101/ws, which flutter run prints.
- get_logs works when a LogCollector is installed, and secondary_tap is available only on desktop.
- connect checks the binding version in the app against the server version.
- A Dart SDK is required, because the bridge installs through dart pub global activate.
How to disable. Run claude mcp remove marionette and drop the dependency with flutter pub remove marionette_flutter along with the MarionetteBinding line in main.dart. The bridge is removed with dart pub global deactivate marionette_mcp.
FAQ
How do I connect Marionette MCP to Claude Code?
After dart pub global activate marionette_mcp run claude mcp add --transport stdio marionette -- marionette_mcp. Setup for Cursor, Gemini CLI, Copilot and Antigravity is in docs/mcp-tools.md.
How does Marionette differ from the official Dart and Flutter server?
The official server handles development tasks: searching packages, managing dependencies, analyzing code and showing runtime errors. It can drive the UI through Flutter Driver. Marionette works with the running app directly and keeps its set of actions small.
What must I do to the app before connecting?
Add marionette_flutter, call MarionetteBinding.ensureInitialized() under kDebugMode in main.dart, run the app with flutter run and copy the VM service address from the console.
Can I target an element without a key?
Yes. A tap finds an element by key, semantics identifier, text, type or coordinates. The author advises the key as the most stable option, with the semantics identifier next.
Is there a command-line version of Marionette?
Yes. The repository has a marionette_cli package and a guide in docs/cli.md. The marionette_flutter package folder also holds a skill, marionette-flutter-drive-app.
Discussion
No questions or reviews yet.
Related
MCP serversA community Playwright MCP server: browser automation, screenshots, device emulation and test code generation
CLI, MCP server and typed Node.js API so an agent can verify its changes in a live mobile app on iOS, Android and more
An MCP server that checks whether the agent is really done: drives the real app and returns pass, fail or couldn't tell with the file and line
The official MCP server debugger: web UI, automation CLI and terminal UI in one package
An MCP server from Mozilla: an agent drives Firefox through WebDriver BiDi, reads the console and network, takes page snapshots and profiles loading
Postman's official MCP server: workspaces, collections, specs and environments straight from your agent
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Marionette MCP: an agent inside a Flutter app (this entry) | no | not required | 497 | |
| Flutter Agent Plugins | yes | 3,123 | the Flutter team plugin: skills and the Dart MCP server for development | |
| Mobile MCP | no | not required | 10,095 | a general server for iOS and Android simulators, emulators and devices |
| Agent Skills for Dart | yes | 532 | Dart team skills: tests, analysis, CLI apps and FFI |
README in short
The README presents the project as the Playwright MCP for Flutter and compares it with the official Dart and Flutter server. The quick start has four steps: prepare the app, install the bridge, configure the AI tool and run the app in debug mode. Links to the LeanCode team's video and article follow, and details are spread across documents: getting started, Flutter setup, configuration, logging, semantics, session reports, custom extensions and troubleshooting.