Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Flutter Driver MCP Launch the Flutter app and tap the login button"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets AI agents see, tap, type, scroll, and assert inside live Flutter apps — no pre-written tests required.
Flutter Driver MCP bridges your LLM (Claude, Gemini, etc.) to a running Flutter application via Flutter's test framework + WebSocket, giving the agent full interactive control of the UI.
Now with screen recording! Record your app sessions as native video files (MP4/MOV) on iOS Simulators, macOS Desktop, and Android devices.
Zero-config injection. No changes to your app's source code. The harness is auto-injected at launch time — just point at a project path and go.
Focused, LLM-optimized toolset. 26 purpose-built tools instead of hundreds. Every tool description fits comfortably in an LLM context window without drowning the model in irrelevant options.
Suggestive errors. When a widget isn't found, the harness fuzzy-matches against the live widget tree and returns "Did you mean…?" suggestions — dramatically reducing agent retry loops and wasted tokens.
Token-efficient inspection. Widget tree output strips Dart generics, flattens layout boilerplate (Container, Padding, SizedBox…), and omits heavyweight coordinate data by default. The agent sees only what matters.
Full WidgetTester power. Every interaction runs through Flutter's real test framework with pumpAndSettle() after each action — no timing hacks, no flaky coordinate-based taps.
Related MCP server: Mobile Device MCP
Category | Tools |
Lifecycle |
|
Interaction |
|
Inspection |
|
Assertions |
|
Navigation |
|
Environment |
|
Utilities |
|
All interaction tools accept a simple target string instead of verbose JSON:
"#my_key" → find by Key
"text=\"Submit\"" → find by text
"type=\"Checkbox\"" → find by widget type
"tooltip=\"Back\"" → find by tooltip
"semanticsLabel=\"Username\"" → find by semantics label (hint text, accessibility label)When a widget isn't found, the harness scans the tree and returns "Did you mean…?" suggestions — dramatically reducing agent retry loops.
┌──────────────┐ JSON-RPC/stdio ┌──────────────────┐ WebSocket ┌──────────────────┐
│ MCP Client │ ◄──────────────────► │ Node.js Server │ ──connects──► │ Dart Harness │
│ (LLM Agent) │ │ (index.ts) │ │ (harness.dart) │
└──────────────┘ └──────────────────┘ │ inside Flutter │
│ flutter_test │
└──────────────────┘The Node.js MCP server receives tool calls from any MCP-compatible client.
On start_app, it injects a Dart harness into the project's integration_test/ directory and launches flutter run --machine.
The harness starts a WebSocket server inside the app. The Node server connects to it and sends JSON-RPC commands.
All interactions (tap, scroll, assert, screenshot, etc.) execute inside the real Flutter test framework with full access to the widget tree.
Zero external dependencies. The harness only imports
dart:*core libraries andpackage:flutter_test(already in every Flutter project). No changes to yourpubspec.yaml, no entitlement edits, no setup steps.
You can run the server directly via npx in your MCP configuration without installing anything globally.
If you instead wish to install it globally:
npm install -g flutter-driver-mcpNode.js ≥ 18
Flutter SDK on your PATH
Any Flutter project — no additional dependencies or setup required
To add this server to Claude Code, run:
claude mcp add flutter-driver -- npx -y flutter-driver-mcpAdd the following to your MCP client configuration:
{
"mcpServers": {
"flutter-driver": {
"command": "npx",
"args": ["-y", "flutter-driver-mcp"]
}
}
}Once your MCP client is connected, just tell the agent what you want — it'll figure out the tools:
"Launch my app at
/path/to/my_appon macOS and test the login flow"
"Verify the account creation flow is working"
"Take a screenshot and verify the home screen loaded"
The agent handles start_app, explore_screen, tap, assert, screenshot, etc. automatically. No need to spell out tool calls.
Tool | Description |
| Injects the harness, launches the app via |
| Gracefully sends |
| Sends a full restart command to the running app (preserves session). |
| Lists available Flutter devices (simulators, emulators, physical, desktop). No running app required. |
| Starts recording the screen of the running app's device. Supports iOS Simulators (MP4), macOS Desktop (MOV), and Android (MP4, max 180s). Auto-stops after 5 minutes or on |
| Stops the current recording and finalizes the video file. Returns the file path, format, duration, and size. Called automatically by |
Tool | Description |
| Taps, long-presses, or double-taps a widget. Set |
| Enters text into a |
| Scrolls or swipes a widget. Use |
| Drags from a source widget to a destination widget or custom pixel offset. |
| Scrolls a scrollable container until a target widget appears. |
| Polls until a widget appears (with timeout). Set |
| Simulates a keyboard key press (enter, tab, escape, backspace, arrow keys, etc.). |
Tool | Description |
| Returns the full widget tree as JSON. Use |
| Returns the Semantics tree — compact, labels-focused, ideal for LLMs. Pass |
| Maps all interactive elements on the current screen using the native Semantics tree. Each element includes a |
| Returns the raw text string from a widget (supports |
| Captures a PNG screenshot. Without a |
Tool | Description |
| Runs an assertion on a widget. Use |
Tool | Description |
| Pushes a named route via |
| Pops the current route or dismisses modal overlays (bottom sheets, dialogs). Falls back to Escape key for overlays that aren't Navigator routes. |
| Returns the name of the currently active route — lets the agent know where it is. |
| Sends the app to background and brings it back after a duration. |
| Toggles WiFi on/off (macOS/iOS Simulator only). |
| Registers a mock HTTP response for a URL pattern. Pass null to clear. |
Tool | Description |
| Returns the last N lines from the app's stdout/stderr. |
| Executes multiple actions in a single tool call (e.g. fill a form: 5× |
| Waits for all animations to finish before proceeding. |
Flutter Driver MCP is complementary to the official Dart/Flutter MCP server. While there is some overlap in app interaction (like widget tree inspection), they serve distinct roles in a developer's workflow:
Feature | Official Dart MCP | Flutter Driver MCP |
Primary Focus | IDE productivity, code analysis & linting | Live AI-Driven E2E Testing |
Connectivity | Dart Tooling Daemon (DTD) | WebSocket to Injected Harness |
App Control | Hot reload/restart, workspace symbols | Mocking, backgrounding, network interception |
AI Discovery | Widget Tree (standard) | Semantics-first ( |
Assertions | Manual tree inspection by agent | On-device assertions ( |
Key Tools |
|
|
Use both together: the official server for deep code analysis, package management, and standard IDE features; use Flutter Driver MCP when you need the agent to live-test the app UI, simulate complex environment states, and verify behavior with high-level assertions.
If you're using both servers in the same project, drop the following into your project's AGENTS.md (or equivalent instruction file) so your AI agent knows when to reach for which:
## MCP Server Usage Guide
This project has two MCP servers. Use the right one for the job:
### Official Dart/Flutter MCP Server
Use for **code-level** work — things you'd do in an IDE:
- Adding/removing packages (`pub add`, `pub remove`)
- Resolving symbols, finding definitions (`resolve_workspace_symbol`, `hover`)
- Running unit/widget tests (`run_tests`)
- Static analysis and formatting (`analyze_files`, `dart_fix`, `dart_format`)
- Hot reload/restart via DTD (`hot_reload`, `hot_restart`)
- Reading package source code (`read_package_uris`)
### Flutter Driver MCP Server
Use for **live UI** work — things a real user would do:
- Launching the app on a device (`list_devices`, `start_app`)
- Tapping, typing, scrolling, swiping, dragging (`tap` with `gesture`, `enter_text`, `scroll` with `direction`, `drag_and_drop`, `press_key`)
- Checking what's on screen (`explore_screen`, `get_widget_tree`, `screenshot`, `get_text`)
- Asserting UI state (`assert` with `check`: `exists`, `not_exists`, `text_equals`, `text_contains`, `count`, `state`, `visible`, `enabled`)
- Mocking network responses (`intercept_network`)
- Navigating (`navigate_to`, `go_back`, `get_current_route`)
- Simulating environment (`simulate_background`, `set_network_status`)
- Executing scoped waits (`wait_for` with `gone` flag)
### Key Rules
- **Hot restart**: Use `pilot_hot_restart` if the app was started via Driver's `start_app`.
Use the official `hot_restart` if working through DTD. Never mix them.
- **Optimal workflow**: Use the Official server to edit code → `pilot_hot_restart` to refresh →
Driver's `explore_screen` or `assert_exists` to verify the change rendered correctly.
- After any Driver interaction (`tap`, `enter_text`, etc.), the harness automatically
calls `pumpAndSettle()`. You don't need manual waits unless testing async network latency.The project includes comprehensive verification scripts:
# Build (includes Dart syntax verification)
npm run build
# Run the full integration test suite
npm run verify-integrationThe integration tests boot a real Flutter app (test_app/), exercise all major tools over JSON-RPC, and verify correct behavior.
MIT
Runs an assertion check on a widget. Use 'check' to specify the type: exists, not_exists, text_equals, text_contains, count, state, visible, or enabled.
Inputs: check (required), target, expected, stateKey, +1 more.
Execute multiple actions in a single call. Each action is run sequentially with pumpAndSettle between them. Stops on first error. Supported tools: tap, enter_text, scroll, assert, wait_for, press_key, screenshot, get_text, explore_screen.
Inputs: actions (required).
Drags from a source widget to a target widget (or to an offset).
Inputs: from (required), dx, dy, to, +1 more.
Enters text into a widget found by the target string. By default, replaces existing text. Set clearFirst to explicitly clear and re-focus the field before typing.
Inputs: text (required), action, target, clearFirst, +1 more.
Maps out interactive elements on the screen.
Inputs: filter, within.
Returns the accessibility (semantics) tree.
Inputs: includeRect.
Returns the name of the currently active route on the Navigator stack.
Inputs: no named parameters.
Returns the text content of a widget identified by the target string.
Inputs: target, timeout_ms.
Returns a JSON representation of the widget tree.
Inputs: summaryOnly.
Pops the current route off the Navigator stack (like pressing the back button).
Inputs: no named parameters.
Mocks a network response. Pass null for both to clear.
Inputs: urlPattern, responseBody.
Lists available Flutter devices. Does NOT require a running app.
Inputs: no named parameters.
Performs a hot restart of the currently running app session started by this server.
Inputs: no named parameters.
Simulates a keyboard key press (e.g. enter, tab, escape, backspace, arrow keys).
Inputs: key (required).
Reads the last N lines from the app's stdout/stderr.
Inputs: lines.
Captures a screenshot. Without a target, captures the full app. With a target, captures a specific widget.
Inputs: type, target, save_path, timeout_ms.
Scrolls or swipes a widget. Use dx/dy for pixel-precise scrolling, or direction/distance for named swipe gestures.
Inputs: dx, dy, target, distance, +2 more.
Scrolls a scrollable widget until a target widget is visible.
Inputs: dx, dy, target, timeout_ms, +1 more.
Simulates network connectivity changes.
Inputs: wifi (required).
Simulates the app going into the background and coming back to the foreground.
Inputs: duration_ms.
Injects the harness and starts the Flutter app in test mode.
Inputs: project_path (required), device_id.
Starts recording the screen of the running app's device. Recording begins capturing immediately with no warmup delay — proceed with interactions right away. Supports iOS Simulators (MP4), macOS Desktop (MOV), and Android devices/emulators (MP4, max 180s). Only one recording at a time. Auto-stops if stop_app is called or after 5 minutes.
Inputs: save_path.
Stops the currently running Flutter app and cleans up.
Inputs: no named parameters.
Stops the current screen recording and finalizes the video file. Returns the file path, format, duration, and file size. Called automatically by stop_app if a recording is active.
Inputs: no named parameters.
Taps, long-presses, or double-taps a widget. Defaults to a normal tap. Use gesture to change.
Inputs: target, gesture, timeout_ms.
Waits for a widget to appear or disappear. Set gone=true to wait for disappearance (e.g. loading spinners).
Inputs: gone, target, timeout, timeout_ms.
Pumps frames for a specified duration without waiting for all animations to settle. Useful for hero transitions, page animations, or custom animation controllers where pumpAndSettle would time out.
Inputs: duration_ms.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 28 tools
Each tool targets a distinct operation: lifecycle (start/stop/restart), device management, gestures (tap/scroll/drag), navigation, inspection, and network simulation. The gesture tools are well differentiated (tap vs enter_text vs scroll vs drag_and_drop), and even similar ones like scroll vs scroll_until_visible have clearly distinct purposes. No meaningful overlap or ambiguity exists.
Tools follow a consistent verb_noun pattern (start_app, stop_app, get_text, wait_for, read_logs). Most names are descriptive and consistent, with minor deviations like 'assert' and 'intercept_network' mixing a bare verb style, and 'explore_screen' vs 'get_widget_tree' showing slight inconsistency in prefix style (explore vs get). Overall quite consistent.
At 28 tools, this is on the heavy side but justifiable given the breadth of a Flutter driver's surface: lifecycle, gestures, navigation, inspection, network, recording, and batching. Each tool earns its place and the count is appropriate for a comprehensive UI automation server, though slightly above the typical ideal range.
The surface is exceptionally complete for a Flutter driver: full app lifecycle (start/stop/restart), device listing, gesture primitives, navigation, text input, widget assertions, screenshots, widget/accessibility trees, network mocking, background simulation, log reading, recording, and batch operations. The batch_actions tool even fills the gap for multi-step efficiency without round trips. No obvious dead ends or missing operations.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
