leancodepl/marionette_mcp

498 stars 54 forks Quality 73 Trend 41Apache-2.0

MCP server enabling AI agents to interact with Flutter apps at runtime - let them inspect widgets, simulate taps, enter text, scroll, and take screenshots.

Overview

Marionette MCP enables AI agents (Claude Code, Copilot, Cursor, Gemini CLI, and more) to inspect and interact with running Flutter applications. It connects your AI agent directly to a running app via the Model Context Protocol (MCP), so it can see the widget tree, tap elements, enter text, scroll, and capture screenshots for automated AI-driven smoke testing and interaction. Marionette MCP keeps the surface area intentionally small. It exposes only a handful of high-signal actions and returns the minimum actionable data, which helps keep prompts focused and context sizes under control. - Video: Clicking Through Your App with Marionette MCP - Article: Marionette MCP - Your Flutter AI Agent That Interacts With Running Apps The official Dart & Flutter MCP server focuses on tasks: searching pub.dev, managing dependencies, analyzing code, and inspecting runtime errors. It can also drive the UI, but it does so through Flutter Driver, which introduces extra instrumentation in your app.

README

Marionette MCP

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

Marionette connects Claude Code, Cursor, Codex, Gemini CLI, Copilot or any MCP client to the Flutter app you run in debug mode. The agent sees the screen, taps, types, scrolls, reads the logs, hot reloads, and writes a report of what it did. If you know Playwright MCP: this is that, for Flutter.

Website · Docs · Video · Article

Quick start

Add the package to your app and initialize the binding in debug builds:

flutter pub add marionette_flutter

void main() {
  if (kDebugMode) {
    MarionetteBinding.ensureInitialized();
  } else {
    WidgetsFlutterBinding.ensureInitialized();
  }
  runApp(const MyApp());
}

Give your agent a bridge: the MCP server or the marionette CLI, whichever you prefer (every agent):

# MCP server, registered with Claude Code
dart pub global activate marionette_mcp
claude mcp add --transport stdio marionette -- marionette_mcp

# or the CLI
dart pub global activate marionette_cli

Run the app with flutter run and paste the ws://…/ws VM service URI it prints into the prompt, or ask the agent to run the app itself:

Connect to ws://127.0.0.1:9101/…/ws. On Profile, a malformed email must show an error and keep Submit disabled, and a valid one must submit.

[!IMPORTANT] Flutter’s own widgets work as is. A custom design system needs one configuration step, or the agent cannot see your buttons and fields: see Configure.

What the agent can do

	Tools
See	`get_interactive_elements`, `take_screenshots`
Act	`tap`, `enter_text`, `scroll_to`, `swipe`, `long_press`, `double_tap`, `pinch_zoom`, `press_key`, `press_back_button`
Verify	`get_logs`, `set_device_config` (text scale, bold text, dark mode)
Iterate	`hot_reload`, `hot_restart`
Extend	your app’s own actions, registered with `registerMarionetteExtension`

With MarionetteConfiguration(enableSessionReports: true), every run leaves a folder: a steps.md the server writes, one line per tool call, and a report.md the agent writes from it. See Reports.

The marionette CLI drives the app with the same actions as shell commands: see Drive.

Agent Skills

marionette_flutter ships three Agent Skills:

Skill	Teaches the agent to
`marionette-flutter-setup`	Add the binding, configure a custom design system, logs and device config
`marionette-flutter-drive-app`	Drive the app with the MCP tools or the CLI, and write the report
`marionette-flutter-to-patrol`	Turn a verified run into Patrol tests

dart run skills@ get                     # in an app that depends on marionette_flutter
npx skills add leancodepl/marionette_mcp # without the Dart toolchain

Documentation

Page	What is inside
Start	Setup, every agent’s config, the first prompt, the example app, FAQ
Concepts	How the agent sees a screen, selectors, compaction, the single-binding rule
Configure	Custom design systems, Semantics, logs, device config, custom extensions
Drive	Prompts for common jobs, every tool with its CLI command, the CLI
Reports	Session folders, `steps.md`, `report.md`, the verdict

Packages

Package	Role
`marionette_flutter`	The binding in your app. Required.
`marionette_mcp`	The MCP server your agent runs.
`marionette_cli`	The `marionette` CLI, for shell-only agents.
`marionette_logging`	Log collection from the `logging` package.
`marionette_logger`	Log collection from the `logger` package.

🛠️ Maintained by LeanCode

Marionette is built by LeanCode, the creators of Patrol, the testing framework for Flutter. We build Flutter products from scratch to long-term maintenance.

View the full README on GitHub

Install

npx skills add leancodepl/marionette_mcp # without the Dart toolchain

New to MCP? Start with the mcpskill.org guide →