Dusk MCP Server
End-to-end driver for Flutter apps: snapshots the Semantics tree, drives gestures such as tap, type, scroll, and drag, captures screenshots, observes live state, and supports hot reload for automating and inspecting running Flutter applications.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
At a glance
Fact | Value |
Package | |
Install |
|
Import |
|
Entry points |
|
Platforms | Any Flutter target that exposes a VM Service in a debug or profile build: Android, iOS, web, macOS, Windows, Linux; viewport and device emulation need Chrome with a CDP port; |
Requires | Dart 3.13, Flutter 3.47; a plugin of |
Dependencies |
|
License | MIT |
Related MCP server: Flutter Driver MCP
Install
flutter pub add tapir
dart run tapir tapir:install
dart run tapir start --device=macos # dowel records the session every tapir:* command dials
dart run tapir tapir:snaptapir:install patches lib/main.dart (the import, WidgetsFlutterBinding.ensureInitialized() when missing, and TapirPlugin.install() inside a !kReleaseMode guard), then scaffolds the fast ./bin/dowel wrapper and registers tapir as a dowel plugin. Re-running it changes nothing. The installation guide also adds dowel as a direct dependency (dart pub add dowel). Wired by hand, main.dart looks like this:
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:tapir/tapir.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
if (!kReleaseMode) {
TapirPlugin.install();
}
runApp(const MyApp()); // MyApp is the host app's root widget.
}The guard is !kReleaseMode, not kDebugMode: debug and profile builds carry tapir (tapir:perf_run measures a profile build) and a release build tree-shakes it. Without the guard tapir ships in release, and anyone who reaches that app's VM Service can drive it. --dart-define=TAPIR_DISABLE=1 skips registration in a build that must not expose the extensions. The example/ app gives each verb a live target widget.
Snapshot and refs
dart run tapir tapir:snap --interactiveOnly
# - textbox "Email" [ref=e1]
# typeable: true
# - button "Sign in" [ref=e2]Token | Minted by | Lifetime |
|
| The same Semantics node keeps its token across snapshots, and a token outlives its widget. A ref whose element left the tree is relocated by label ( |
|
| Re-resolved against the live tree on every action; survives rebuilds |
Narrow a read with --within=<eN>, --interactiveOnly and --grep=<regex>; they compose. --includeEnrichers adds Wind state under each W-widget that has a className: up to seven contract fields, of which bgColor and textColor appear only when they resolve (tapir:observe keeps only breakpoint and states unless you pass --includeEnrichers=full; the host calls Wind.installDebugResolver() from wind_kit, read through wind_kit_diagnostics_contracts) and Magic state (MagicTapirIntegration.install() from package:magic_devtools/tapir.dart, after Magic.init(); it exists only in a magic_devtools release built on tapir, and tapir:install warns and skips it otherwise; see Magic integration). A ref line ending in [offscreen] or [occluded] names why an action would fail before you try it.
Actions and the actionability gate
dart run tapir tapir:tap --ref=e2 --snapshot=diff
dart run tapir tapir:fill --ref=e1 --text="ada@example.com" --jsonGestures (tap, hover, drag, scroll, double_click, right_click, triple_click) and text verbs (type, clear, fill, press_key) dispatch real pointer and key events into the widget tree. tap, hover, drag, the click variants, type, fill and set_checkbox (on the control it taps) first pass the gate (clear, scroll, press_key and select_option skip it), in a fixed order, and a refusal names the reason an agent can branch on:
Check | Refusal substring | Recovery |
Defunct (preflight) |
| Re-snap |
Enabled |
| Re-snap; the widget may enable later |
Zero rect |
| Re-snap or re-find |
Off-viewport (scrolls into view first) |
|
|
Stable across two frames |
| Wait for the animation; |
Receives events (hit test) |
| Dismiss the overlay ( |
A green tick is dispatch, not effect. Add --json to print the whole response and read the effect block: effect.changed for tap and scroll, effect.verified and effect.value for type, fill and clear. When the hit test could not answer (routine on a web debug build) the response of a gated verb such as tap, type or fill carries a checks block with receivesEvents: indeterminate instead of a silent pass. A target tapir will not act on at all (a ref that is not a text field, say) answers the error type refused (code -32001), and a value it cannot use answers invalid_param. tapir:run "tap --ref=e5" "snap --grep Counter" batches verbs into one round trip.
Waiting and observing
dart run tapir tapir:observe --roles=button,textbox # q<N> handles, re-resolved per action
dart run tapir tapir:wait_for --text="Welcome back" --timeoutMs=5000Verb | Returns |
| Waits for |
| Waits until in-flight HTTP requests stay at zero for |
| A flat candidate list of interactive widgets with |
| In-app |
| The router's location and the top page ( |
When the app is not producing frames (a hidden window or a backgrounded tab) tapir forces frames outside the web and reports framesForced: true; where it cannot, every response carries a warnings block rather than a stale answer that looks fresh. See frame production.
Screenshots and web
dart run tapir tapir:screenshot --output=shot.jpg
dart run tapir start --device=chrome --cdp-port=9333
dart run tapir tapir:device_profile --preset=pixel-8Surface | Behaviour |
| JPEG (default) or PNG of the viewport, or of one widget with |
Web screenshot | With |
| Presets |
| Hot reload, then snapshot, screenshot and recent exceptions in one round trip |
Performance tracing
dart run tapir tapir:perf_begin --mode=attribution
dart run tapir tapir:tap --ref=e7
dart run tapir tapir:perf_endVerb | Does |
| Bracket one interaction; |
| The rows behind one insight of the last report |
| Repeat a scenario from a clean start and write medians, judge one run against another, run a campaign of scenarios from cold starts |
| The last session as a Chrome Trace JSON for |
MCP server and clients
The tapir_* tools ride on the dowel MCP server, so the client config key is dowel. dart run tapir mcp:install writes the entry into .mcp.json: ./bin/dowel mcp:serve when the fast wrapper exists on a POSIX host, and dart run tapir mcp:serve otherwise (always on Windows, where ./bin/dowel is not used). Standard config for any client that reads .mcp.json:
{ "mcpServers": { "dowel": { "command": "./bin/dowel", "args": ["mcp:serve"], "cwd": "." } } }Client | Install |
Claude Code |
|
VS Code |
|
Cursor |
|
Windsurf |
|
Goose, Warp | Paste the standard config into Goose (Advanced settings, Extensions, Add custom extension) or Warp (Settings, AI, Manage MCP Servers) |
Claude Desktop |
|
Codex |
|
Without tapir you hot reload, take a screenshot, drag the PNG into the chat, paste the widget source and ask why the button does nothing. With it the agent calls tapir_snap, then tapir_tap on e7: the gate checks the button, the tap lands and a fresh snap confirms it. A timing issue no longer needs a Future.delayed and a re-run to tell it from a bug, because the gate refuses with a reason that names the cause (not stable, obscured by, off-viewport).
For AI coding agents
Do | Because |
Install tapir only behind | Anyone who reaches the VM Service of a build that carries tapir can drive the app |
Start the app with | Every |
Snap again after a navigation or rebuild, or use a |
|
Narrow a snapshot with | A full tree costs context, and a sidebar that repeats page labels misleads an exact-label lookup |
Read | A tick says the event left tapir, not that the widget took it |
Branch on the leading refusal substring, never on the trailing detail | The substrings and the gate order are a frozen contract; the detail is not |
Read | A hidden window or tab stops frames, and the tree then reads as a broken screen |
Check | A refused session carries no metrics |
Point the MCP client at the | The tools ride on the dowel server, and clients do not reload an entry on their own |
Dependencies
dowel for the CLI, the MCP server and the VM Service connection; wind_kit_diagnostics_contracts to read Wind state without depending on Wind; image for screenshot encoding; yaml and meta. The rest is the Flutter SDK.
Links
Documentation: installation, quickstart, every command, MCP setup, the actionability gate, Magic and Wind integration, and the MCP tool reference, and moving from
fluttersdk_duskllms.txt and the agent skill for AI coding agents:
npx skills add anilcancakir/tapir
License
MIT, see LICENSE. Built by Anılcan Çakır.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
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.
remote debug iOS/Android/Unity/Godot/Flutter/RN/Web on real-device.ui-tree/screenshots/taps,tests.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Flutter in-app bug tracking, visual pin annotations, and device logs directly into your AI IDE.
Related MCP Servers
- AlicenseCqualityBmaintenanceA Model Context Protocol server that connects Flutter apps with AI coding assistants like Cursor, Claude, and Cline, enabling AI-powered analysis of widget trees, navigation, and layout issues.62399MIT
- AlicenseBqualityDmaintenanceAn MCP server that lets AI agents see, tap, type, scroll, and assert inside live Flutter apps — no pre-written tests required.28MIT
- AlicenseNot gradedqualityBmaintenanceExposes a stdio JSON-RPC tool surface that lets AI agents control running Flutter and Dart apps — starting, stopping, reloading, and hot-restarting sessions, reading logs, running doctor/list/tinker checks, and invoking plugin-contributed tools. It gives agents one shared protocol instead of ad hoc shell scripts.2MIT
- AlicenseBqualityBmaintenanceEnables AI agents to automate Android and iOS devices, including emulators and physical devices, by capturing screenshots, reading UI accessibility trees, performing touch and text input, and managing app lifecycle and logs.184MIT