Skip to main content
Glama
fluttersdk

Dusk MCP Server

by fluttersdk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Dart
Local

NOTE

Requires Dart SDK >= 3.4.0 and Flutter >= 3.22.0. dusk is debug-only: production builds tree-shake the entire driver across web, desktop, and mobile.

Installation

flutter pub add fluttersdk_dusk
dart run fluttersdk_dusk dusk:install      # patches lib/main.dart + scaffolds ./bin/fsa + registers dusk plugin

That's it. After the second command, all 36 dusk:* commands surface through ./bin/fsa <cmd> (~110ms warm) or dart run fluttersdk_dusk <cmd> (works the same, ~3s startup), and the MCP server is one dart run fluttersdk_dusk mcp:install away. When fastcli (./bin/fsa) is absent, mcp:install writes dart run fluttersdk_dusk mcp:serve into .mcp.json automatically; no manual edit required. See MCP install: 8 clients for the per-client wiring. Manual wiring, Magic-stack integration, and the full per-command flag reference live in the Getting Started guide.

TIP

fastcli is the AOT-compiled artisan dispatcher (~110ms warm) shipped as ./bin/fsa. dusk:install scaffolds it for you automatically (best-effort; falls through to a warning when dart is not on PATH). After that, every ./bin/fsa <cmd> is the fast path. The CLI also runs as dart run fluttersdk_dusk <cmd> with the same surface, ~3s slower per call.

Related MCP server: Flutter MCP Service

Why Dusk?

End-to-end testing on Flutter has always been a stitched-together ritual. flutter_driver ships a one-off socket protocol that does not survive hot restart. integration_test runs in-process against a simulated WidgetTester, but you write a test file, build, run, and wait. AI coding agents that want to drive the running app reach for ad hoc flutter test invocations, copy stack traces back into the prompt, and paste screenshots back, calling it a workflow.

Dusk closes that loop. A single VM Service extension family (ext.dusk.*), a single CLI namespace (dusk:*), and a single stdio MCP server back 36 CLI commands and 35 MCP tools (32 ext.dusk.* + 3 artisan:dusk:* substrate-routed). The same contracts power human-driven terminal calls and agent-driven MCP tool calls: dusk:tap --ref=e7 (CLI) and dusk_tap (MCP) reach the exact same code path. No test harness, no test file, no build step. Attach to the live app and the agent has eyes (dusk_snap, dusk_screenshot, dusk_observe) and hands (dusk_tap, dusk_type, dusk_scroll, dusk_drag). On Flutter web, the dusk:screenshot CLI command falls back to CDP Page.captureScreenshot when artisan was started with --cdp-port, bypassing the in-isolate extension that hangs under CanvasKit; the dusk_screenshot MCP tool still dispatches in-isolate, so web agents should use the CLI for screenshots. dusk_exceptions captures non-fatal FlutterErrors (including overflow) in-package so diagnostics work even without telescope.

Tool

What it does

Where Dusk fits

integration_test (Flutter SDK)

In-process WidgetTester wrapper; runs tests via flutter drive

Different niche: integration_test owns the authored test file; Dusk owns the unscripted running app. Use both.

patrol (Leancode, 694 likes)

Native UI permissions + dialogs layered on integration_test

Orthogonal: patrol owns authored tests with native dialogs; Dusk owns unscripted automation by humans and AI agents.

flutter_driver (Flutter SDK, legacy)

One-off socket protocol; being phased out

Dusk is hot-restart safe via registerExtensionIdempotent (16 aggregator register functions), one contract for CLI and MCP, no test harness, no separate isolate.

maestro (13.7K stars)

YAML DSL over OS accessibility layer

Dusk drives the Flutter widget tree directly (Semantics nodes + RenderObjects); no Flutter Desktop limitation; zero YAML to author.

mcp_flutter (298 stars)

Flutter MCP toolkit with fmt_* tools

Dusk is on pub.dev with verified publisher, framework-native Artisan plugin, e<N> and q<N> ref system, 6-step actionability gate.

playwright-mcp (33K stars)

Browser MCP via accessibility tree + [ref=eN] tokens

The Flutter-native equivalent. Dusk's q<N> handles mirror Playwright's getByRole(); dusk_observe borrows Stagehand's observe-once-act-many pattern, ported to Flutter Semantics.

Features

Feature

Description

🌳

Semantics Snapshot

dusk_snap emits a YAML tree with stable [ref=eN] tokens; every action targets a ref, no brittle XPath or coordinate guessing

🛠️

36 CLI Commands

snap, tap, type, fill, drag, scroll, hover, dblclick, right_click, triple_click, focus, blur, clear, set_checkbox, select_option, press_key, wait, find, observe, navigate, modal, reset_overlays, screenshot, hot_reload_and_snap, CDP resize + device, close_app, install, doctor, perf_begin + perf_end

🤖

35 MCP Tools

The full CLI surface plus dusk_evaluate, exposed as stdio JSON-RPC tools to Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible agent

🚪

6-Step Actionability Gate

Every gesture passes defunct (preflight) → enabled → zero-rect → off-viewport (auto-scrolls) → stable (2-frame rect drift) → receives-events (hit-test path); no flaky taps, and a checks block when the last one could not be proven rather than a silent pass

🔖

Playwright-style Locators

q<N> re-resolvable handles via dusk_find walk the live Semantics tree on every action. Stale handles throw, never silently act on the wrong widget

🔄

Hot Reload + Snap Round-trip

dusk_hot_reload_and_snap returns {reloaded, durationMs, snapshot, screenshot, exceptions} in one call

🖥️

CDP Device Emulation

dusk_resize_viewport and dusk_device_profile (iphone-x, pixel-5, desktop-1440, plus 5 more) drive Chrome DevTools Protocol

📈

Frame Attribution Session

dusk_perf_begin / dusk_perf_end bracket a driven interaction and report which widget types built, how often and for how long, next to wind's cache hit/miss/bypass counters and magic's controller notifies. A session the engine did not render through is REFUSED rather than reported, because a table of zeros reads as "fast"

🎨

Snapshot Enricher Plug-in

DuskPlugin.enrichers.add() lets magic and wind add framework-specific YAML fragments via a frozen String? Function(Element, RefRegistry) contract

🔒

Debug-Only Tree-Shake

Consumer wraps DuskPlugin.install() in kDebugMode; release builds tree-shake the entire driver across web, desktop, and mobile

📡

AI-first Distribution

Canonical fluttersdk-dusk skill at skills/fluttersdk-dusk/ and hosted docs MCP at mcp.fluttersdk.com, distributed to 8+ agents (Claude Code, Cursor, OpenCode, Gemini CLI, VS Code Copilot, Codex CLI, Cline, Roo Code) via fluttersdk/ai. First end-to-end driver in the Flutter ecosystem to ship its own LLM-agent skill bundle + docs MCP.

IMPORTANT

DuskPlugin.install() must be wrapped in if (kDebugMode) { ... } at the call site in lib/main.dart. Release builds tree-shake the entire driver across web (dart2js), desktop (dart2native), and mobile (AOT), but only when the guard exists. Without the guard, dusk ships into release binaries.

AI Coding Assistants

Dusk ships AI-first. The skill at skills/fluttersdk-dusk/SKILL.md teaches your agent the 6 core laws, the e<N> / q<N> ref grammar, the 6-step actionability vocabulary, the 35 MCP tool surface, and the agent-workflow playbooks. The same skill is distributed through fluttersdk/ai for Claude Code, Cursor, OpenCode, Gemini CLI, VS Code Copilot, Codex CLI, Cline, and Roo Code, one command:

npx skills add fluttersdk/ai --skill fluttersdk-dusk

The hosted MCP server at mcp.fluttersdk.com exposes a search-docs tool over Streamable HTTP (no auth) for agents that need to query the dusk docs corpus directly. For stdio-only clients, the npx @fluttersdk/mcp bridge proxies stdio to the upstream HTTP server. The LLM-readable inventory lives at llms.txt. Full multi-client wire-up and the OpenCode registry URL live in the fluttersdk/ai README.

This is independent of dusk's own runtime MCP server (./bin/fsa mcp:serve, covered in the next section): the docs MCP teaches the agent ABOUT dusk; the runtime MCP gives the agent eyes and hands on a running Flutter app.

MCP install: 8 clients

Dusk is the first Flutter MCP server focused on UI automation (tap, snap, screenshot, observe) rather than runtime telemetry. The 35 dusk_* tools surface to any MCP-compatible agent.

NOTE

Configs below use./bin/fsa (the fastcli wrapper, see top of README). If fastcli is not scaffolded yet, swap ./bin/fsa mcp:serve for dart run fluttersdk_dusk mcp:serve in every client row.

Standard config (any client that reads .mcp.json in the project root):

{
  "mcpServers": {
    "fluttersdk": {
      "command": "./bin/fsa",
      "args": ["mcp:serve"],
      "cwd": "."
    }
  }
}

Client

Install

Claude Code

claude mcp add fluttersdk -- ./bin/fsa mcp:serve

VS Code

code --add-mcp '{"name":"fluttersdk","command":"./bin/fsa","args":["mcp:serve"]}', or drop the standard config into .vscode/mcp.json

Cursor

Settings > MCP > Add new MCP Server, or drop the standard config into ~/.cursor/mcp.json

Windsurf

Drop the standard config into ~/.codeium/windsurf/mcp_config.json

Goose

Advanced settings > Extensions > Add custom extension; paste the standard config

Warp

Settings > AI > Manage MCP Servers, or /add-mcp slash command with the standard config

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and add the standard config under mcpServers

Codex

codex mcp add fluttersdk ./bin/fsa mcp:serve

Before / after

Without Dusk

With Dusk

You hot-reload, screenshot the result, drag the PNG into Claude, type "the counter button should be tappable but isn't, what's wrong?", scroll, copy the relevant widget source, paste back.

Claude calls dusk_snap and reads the YAML tree with [ref=eN] tokens. Claude calls dusk_tap --ref=e7, the gate fires, the counter increments, Claude verifies via a fresh snap. Loop closes without you in the middle.

You wonder if the failing test is a timing issue or a real bug. You add Future.delayed(Duration(seconds: 2)) and re-run.

The 6-step actionability gate fires before every gesture: defunct, not enabled, zero rect, off-viewport, not stable, obscured by another widget. Errors carry agent-parseable reason strings.

Typical agent session

[agent] artisan_start { device: macos }            # launch the app
[agent] dusk_snap {}                                # semantic tree with stable refs
[agent] dusk_observe {}                             # structured candidate list (Stagehand-style)
[agent] dusk_tap { ref: "e7" }                      # tap a button by ref
[agent] dusk_screenshot { format: "jpeg" }          # verify visually
[agent] dusk_hot_reload_and_snap {}                 # reload + snap in one round-trip
[agent] artisan_stop                                # tear down

Full per-tool input schemas + example calls in the MCP tool reference. For agents that read structured project context at attach time, the canonical entry point is llms.txt; it lists the 35 MCP tool names inline, plus the command surface, ref token grammar, and 6-step actionability vocabulary. The site serves the bare URLs to humans and the same paths with a .md suffix to LLM agents (e.g. https://fluttersdk.com/dusk/getting-started.md).

Examples

The example/ directory ships a vanilla Flutter showroom that gives every CLI command a live target widget on one route: TextField, Dropdown, Checkbox, Switch, counter button, Draggable + DragTarget, dialog, bottom sheet, 30 ListTile rows for scrolling, and navigation buttons across three named routes.

cd example && flutter pub get
dart run fluttersdk_dusk start --device=macos

Documentation

Full docs with live examples at fluttersdk.com/dusk: commands catalog, MCP tool reference, the 6-step actionability reference, Magic and Wind integration guides, and the snapshot enricher authoring guide. The internal architecture lives in ARCHITECTURE.md for contributors.

Contributing

git clone https://github.com/fluttersdk/dusk.git
cd dusk && flutter pub get
flutter test && dart analyze

CI enforces 80%+ line coverage on lib/ on every push to master and every PR back into it, with zero analyze issues and zero format drift on lib/, test/, and bin/. New behavior ships with a failing test first (red, green, refactor).

Before opening a pull request, run the same checks CI runs:

dart format --output=none --set-exit-if-changed lib/ test/ bin/
dart analyze lib/ test/ bin/
flutter test --exclude-tags=integration --coverage --timeout=30s
dart pub publish --dry-run

Report a bug · Request a feature

License

MIT, see LICENSE for details.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Enhanced ADB MCP Server

    rahulkr
    A
    license
    C
    quality
    D
    maintenance
    Enables comprehensive control of Android devices via ADB for Flutter development, UI testing, and visual QA workflows. Provides 60+ tools for device management, UI inspection, app testing, performance profiling, and debugging through natural language.
    77
    MIT

  • mobile-device-mcp

    saranshbamania
    A
    license
    A
    quality
    D
    maintenance
    MCP server that gives AI coding assistants the ability to see and interact with mobile devices. 49 tools for Android/iOS — AI-powered visual analysis (Claude + Gemini), smart tap/type by description, Flutter widget tree inspection, video recording, and test script generation. 4-tier element search with <1ms local matching. Free tier included, zero setup via npx.
    49
    38 npm
    4
    Business Source 1.1