Marionette MCP connects an AI agent to a running Flutter application through the Model Context Protocol (MCP), so the agent can drive the live app rather than only read its code. Once connected, the agent sees the widget tree, taps elements, enters text, scrolls, and captures screenshots, which supports AI-driven smoke testing and interaction.
The project keeps its surface small on purpose: it exposes a handful of high-signal actions and returns the minimum actionable data, which keeps prompts focused and context sizes down. It targets runtime interaction specifically, distinct from the official Dart and Flutter MCP server that focuses on development-time tasks like searching pub.dev, managing dependencies, and analyzing code. Standard Material widgets work without changes, while a custom design system needs configuration so the agent can see and tap custom controls.
It ships as several Dart packages: a binding you add to the app, the MCP server that bridges agents to it, a CLI alternative for shell-only environments, and log-collector adapters. An app can expose its own actions to the agent as custom extensions, for example navigating by route name, seeding test data, or toggling feature flags. An agent skill teaches an agent to prepare an app and drive it without the full instructions in context.
Features
- Runtime interaction: inspects the widget tree and taps, double-taps, long-presses, swipes, pinch-zooms, scrolls, and enters text in a running app
- Screenshots and logs: captures screenshots, reads app logs, and triggers hot reload
- Small toolset: exposes a focused set of actions and returns minimal data to keep agent context small
- Custom extensions: an app registers its own actions as agent tools, such as route navigation, test-data seeding, and feature-flag toggles
- Design-system support: standard Material widgets work out of the box, with configuration for custom design systems
- Agent skill: a SKILL.md teaches an agent to prepare and drive an app, installable through Dart package skills or directly from the repo
- Packages: a Flutter binding, the MCP server, a CLI alternative, and log-collector adapters for the logging and logger packages
- AI tool support: configures for Claude Code, Cursor, Gemini CLI, Copilot, and Antigravity
