Marionette MCP connects coding agents such as Claude Code, Copilot, Cursor, and Gemini CLI to a running Flutter application over the Model Context Protocol. The agent reads the widget tree, taps and long-presses elements, enters text, scrolls, and captures screenshots, which makes it usable for agent-driven smoke testing and interactive debugging of a live app.
It works by adding the marionetteflutter binding to the app's main.dart (initialised in debug mode only) and running the marionettemcp server as a bridge; the agent connects to the app through the Dart VM service URI printed by flutter run. Standard Material widgets are discoverable without further work, while apps built on a custom design system need configuration so the agent can see and target custom buttons and fields.
The toolset is deliberately small and returns minimal data to keep prompt context in check. Where the official Dart and Flutter MCP server targets development-time tasks (pub.dev search, dependency management, code analysis) and drives UI through Flutter Driver, Marionette focuses only on runtime interaction with few changes to the app.
Features
- Widget inspection: getinteractiveelements lists what the agent can act on
- Gestures: tap, secondarytap, doubletap, longpress, swipe, pinchzoom, and scroll_to
- Text entry and navigation: entertext and pressback_button
- Screenshots: take_screenshots for visual verification
- Log access: get_logs via adapters for the logging and logger packages or a custom collector
- Hot reload: trigger hot_reload from the agent
- Custom extensions: register app-specific actions with registerMarionetteExtension, such as navigating by route name, seeding test data, or toggling feature flags
- Semantics support: make custom-painted or rich content readable to agents
- CLI alternative: marionette_cli for shell-only or restricted environments
- Debug-only binding: MarionetteBinding initialises under kDebugMode, leaving release builds unchanged
