Marionette
MCP server enabling AI agents to interact with Flutter apps at runtime - let them inspect widgets, simulate taps, enter text, scroll, and take screenshots.
What is Marionette?
Marionette is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server enabling ai agents to interact with flutter apps at runtime - let them inspect widgets, simulate taps, enter text, scroll, and take screenshots.
MCP server enabling AI agents to interact with Flutter apps at runtime - let them inspect widgets, simulate taps, enter text, scroll, and take screenshots.
This server falls under the Browser Automation category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- MCP server enabling AI agents to interact with Flutter apps
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx marionetteConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Marionette
Marionette MCP is a Dart/Flutter toolkit that lets AI agents interact with running Flutter applications at runtime, enabling programmatic inspection of the widget tree, simulation of user gestures (taps, text entry, scrolling), screenshot capture, log retrieval, and hot reload—all through the Model Context Protocol. It consists of three components: a marionette_flutter package you add to your app, a marionette_mcp server that exposes the MCP tools, and a marionette_cli for direct terminal-based control. Teams use it for AI-driven UI testing, automated QA workflows, and giving Claude or Cursor the ability to visually verify Flutter UI changes in real time.
Prerequisites
- Flutter SDK installed with Dart 3.0 or later
- The Flutter app must run in debug or profile mode (VM Service is required; production builds will not work)
- dart pub global or a local dev dependency setup for the marionette_mcp server
- An MCP-compatible client such as Claude Desktop, Cursor, or Claude Code
Add marionette_flutter to your Flutter app
Add the marionette_flutter package as a dependency in your Flutter project's pubspec.yaml.
flutter pub add marionette_flutterInitialize MarionetteBinding in main.dart
Replace WidgetsFlutterBinding with MarionetteBinding in your app's entry point. This must be the only binding initialized. Only activate it in debug mode to avoid any production impact.
import 'package:marionette_flutter/marionette_flutter.dart';
import 'package:flutter/foundation.dart';
void main() {
if (kDebugMode) {
MarionetteBinding.ensureInitialized();
} else {
WidgetsFlutterBinding.ensureInitialized();
}
runApp(const MyApp());
}Run your Flutter app and note the VM Service URI
Launch the app with flutter run. The VM Service URI is printed to the console output and is required to connect Marionette.
flutter run
# Copy the VM service URI from output, e.g.:
# ws://127.0.0.1:8181/wsInstall and start the MCP server
Install marionette_mcp globally via dart pub and start it. It will wait for an MCP client to connect.
dart pub global activate marionette_mcp
marionette_mcpAdd the server to your MCP client config
Register marionette_mcp in your Claude Desktop or Cursor MCP configuration.
{
"mcpServers": {
"marionette": {
"command": "marionette_mcp",
"args": []
}
}
}Connect to your running Flutter app
From your AI client, call the connect tool with the VM Service URI you noted in step 3.
Marionette Examples
Client configuration
Claude Desktop or Cursor MCP config for the Marionette server.
{
"mcpServers": {
"marionette": {
"command": "marionette_mcp",
"args": []
}
}
}Prompts to try
Prompts that use Marionette's MCP tools to interact with a running Flutter app.
- "Connect to the Flutter app at ws://127.0.0.1:8181/ws and take a screenshot of the current screen."
- "Get all interactive elements on the current screen and list their keys and labels."
- "Tap the button with key 'submit_button' and then take a screenshot to show the result."
- "Enter the text '[email protected]' into the email field and then tap the Login button."
- "Scroll to the element with key 'privacy_policy_link' and tap it, then capture the resulting screen."
- "Hot reload the app after I've changed the button color and show me a screenshot."Troubleshooting Marionette
connect tool fails with 'Unable to connect to VM Service'
The VM Service URI changes every time you run 'flutter run'. Copy the current URI from the flutter run console output—it looks like ws://127.0.0.1:<PORT>/ws. Make sure the app is actually running before connecting.
MarionetteBinding conflicts with another binding causing a FlutterError
MarionetteBinding must be the only binding initialized. Remove any other WidgetsFlutterBinding.ensureInitialized() calls. If you need both in tests, use Platform.environment.containsKey('FLUTTER_TEST') to switch bindings conditionally.
get_interactive_elements returns an empty list for custom widgets
Custom widgets are not automatically recognized as interactive. Configure them by providing an isInteractiveWidget callback during MarionetteBinding initialization, or wrap them with a standard Flutter interactive widget that Marionette recognizes.
Frequently Asked Questions about Marionette
What is Marionette?
Marionette is a Model Context Protocol (MCP) server that mcp server enabling ai agents to interact with flutter apps at runtime - let them inspect widgets, simulate taps, enter text, scroll, and take screenshots. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Marionette?
Follow the installation instructions on the Marionette GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Marionette?
Marionette works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Marionette free to use?
Yes, Marionette is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.
Marionette Alternatives — Similar Browser Automation Servers
Looking for alternatives to Marionette? Here are other popular browser automation servers you can use with Claude, Cursor, and VS Code.
Chrome DevTools MCP
★ 40.6kAI-powered Chrome automation server with natural language element detection. Control Chrome browser through MCP protocol for testing, debugging, and performance analysis. Features 91% accuracy in element location, works with free AI models, and suppo
UI TARS Desktop
★ 34.9k📇 🏠 - Browser automation capabilities using Puppeteer, both support local and remote browser connection.
Playwright
★ 32.8kA production-ready browser automation server that enables AI assistants to interact with web pages using tools for navigation, element interaction, and data extraction. It features a built-in Inspector UI and robust crash recovery for reliable automa
Page Agent
★ 18.0kJavaScript in-page GUI agent. Control web interfaces with natural language.
Chrome
★ 11.7kAn extension-based MCP server that enables AI assistants to control your browser, leveraging existing sessions and login states for automation and content analysis. It provides over 20 tools for semantic tab search, interactive element manipulation,
LAMDA
★ 7.8kThe most powerful Android RPA agent framework, next generation mobile automation.
Browse More Browser Automation MCP Servers
Explore all browser automation servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Marionette in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Marionette?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.