flutter-ultra-mcp

A Claude Code plugin that gives your AI agent full control over Flutter apps across all platforms. 8 isolated MCP servers, 295 tools, 2 Dart packages, and 31 built-in skills — installed with a single command.

Why

A monolithic Flutter MCP server crashes badly: a malformed pubspec.yaml or a flaky AT-SPI binding takes down hot reload, gestures, browser, and native automation in one shot. flutter-ultra-mcp splits the surface across 8 independent processes so a Playwright timeout can't kill your hot reload, and a broken pubspec can't block your running test.

Quick start

# 1. Install the Claude Code plugin
/plugin install Bdaya-Dev/flutter-ultra-mcp

# 2. Add the Dart package to your Flutter project
flutter pub add ultra_flutter

# 3. Initialize the binding in main.dart

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:ultra_flutter/ultra_flutter.dart';

void main() {
  if (!kReleaseMode) {
    UltraFlutterBinding.ensureInitialized();
  } else {
    WidgetsFlutterBinding.ensureInitialized();
  }
  runApp(const MyApp());
}

Start a debug session (flutter run -d chrome), open Claude Code, and ask it to take a screenshot or run /flutter:tour.

Architecture

Each server runs as its own Node.js process. Crash isolation means a bug in one server cannot affect the others. Servers share session state through small JSON files on disk — if a server restarts, it picks up where it left off.

| Server | Tools | What it does | | ------------------------------ | ------: | ------------------------------------------------------------------------------------------------------------------------ | | flutter-ultra-build | 97 | Pub dependencies, code generation, analysis, formatting, tests, platform builds, l10n, assets, signing, project creation | | flutter-ultra-runtime | 56 | Attach to debug sessions, widget tree, VM service method calls, performance profiling, design audit, logs, HTTP capture | | flutter-ultra-browser | 35 | Playwright web automation — network mocking, offline sim, OAuth, drag-drop, dialogs, tracing, console, storage | | flutter-ultra-native-mobile | 43 | Android + iOS — a11y tree, permissions, file picker, notifications, share sheet, CCT/SVC, GPS, deep links, app mgmt | | flutter-ultra-gesture | 19 | Tap, swipe, scroll, text input, multi-touch W3C Actions, screenshots, screencast via ultra_flutter mixin | | flutter-ultra-patrol | 31 | Orchestrate patrol_cli for E2E tests across web, Android, and iOS — run, poll, record, screenshot | | flutter-ultra-native-desktop | 9 | Windows (UIA), macOS (Accessibility), Linux (AT-SPI) — window listing, a11y tree, clicks, file dialogs, remote SSH | | flutter-ultra-devtools | 5 | Live MCP activity panel inside Flutter DevTools — sessions, tool calls, errors, screenshot grid | | Total | 295 | |

See docs/architecture.md for the full design.

Skills

Skills teach Claude the correct tool call sequences for common workflows. Invoke them with /flutter:<name>.

Workflow skills (12)

| Skill | Description | | ------------------------ | -------------------------------------------------------------------------------------------- | | /flutter:setup | One-command setup of flutter-ultra in an existing codebase | | /flutter:tour | Route-by-route screenshot sweep for visual documentation and regression checks | | /flutter:drive | Multi-step user flow automation (login, checkout, onboarding) | | /flutter:debug | Attach to a running app and triage errors from stack trace, widget tree, and network traffic | | /flutter:test | Orchestrate unit, widget, golden, and patrol E2E tests with focused reporting | | /flutter:bisect | Automated git bisect using test results as the oracle | | /flutter:scaffold | Generate project boilerplate following conventions detected in the existing codebase | | /flutter:design-audit | Audit the live app for accessibility, layout, spacing, and design-system conformance | | /flutter:design-verify | Compare the running app against Figma mockups for design-implementation drift | | /flutter:figma-push | Push Flutter web app UI to Figma as editable layers from live screenshots | | /flutter:record-demo | Record a video or GIF demo of an app flow (web browser or native device) | | /flutter:devtools | Wire up and use the DevTools panel for live MCP activity inspection |

Teaching skills (19 — vendored from flutter/skills + dart-lang/skills)

Each teaching skill includes a Flutter Ultra Integration section mapping to the MCP tools that execute the workflow it teaches.

| Skill | Description | | -------------------------------------------- | -------------------------------------------------------------------- | | /flutter:add-integration-test | Configure Flutter Driver and write integration tests | | /flutter:add-widget-preview | Add @Preview annotations for real-time widget previewing | | /flutter:add-widget-test | Write component-level tests with WidgetTester | | /flutter:apply-architecture-best-practices | Structure apps with MVVM + Repository layered architecture | | /flutter:build-responsive-layout | Build adaptive layouts with LayoutBuilder and MediaQuery | | /flutter:fix-layout-issues | Diagnose and fix RenderFlex overflow and unbounded constraint errors | | /flutter:implement-json-serialization | Manual JSON mapping with fromJson/toJson | | /flutter:setup-declarative-routing | Configure go_router with deep linking and nested navigation | | /flutter:setup-localization | Set up flutter_localizations with ARB files | | /flutter:use-http-package | Execute HTTP requests with the http package | | /flutter:add-unit-test | Write unit tests with package:test | | /flutter:build-cli-app | Build Dart CLI apps with argument parsing and compilation | | /flutter:collect-coverage | Collect LCOV coverage reports | | /flutter:fix-runtime-errors | Resolve type system, null safety, and static analysis errors | | /flutter:generate-test-mocks | Generate mock objects with package:mockito + build_runner | | /flutter:migrate-to-checks-package | Migrate from expect/matcher to package:checks | | /flutter:resolve-package-conflicts | Fix pub get version conflicts | | /flutter:run-static-analysis | Run dart analyze and dart fix | | /flutter:use-pattern-matching | Apply switch expressions and Dart 3 pattern matching |

Installation

Plugin (required)

/plugin install Bdaya-Dev/flutter-ultra-mcp

This registers all 8 MCP servers and 31 skills automatically. No manual configuration needed.

Dart package (required for gesture and screencast tools)

Add ultra_flutter to your app's dependencies (not dev_dependencies — the binding must be present in the compiled app):

flutter pub add ultra_flutter

Then initialize the binding in your main.dart:

import 'package:flutter/foundation.dart';
import 'package:ultra_flutter/ultra_flutter.dart';

void main() {
  if (!kReleaseMode) {
    UltraFlutterBinding.ensureInitialized();
  } else {
    WidgetsFlutterBinding.ensureInitialized();
  }
  runApp(const MyApp());
}

Composing with Sentry

UltraFlutterBinding is a mixin on WidgetsBinding, not a subclass. It composes with other binding mixins like Sentry's:

// ignore: implementation_imports
import 'package:sentry_flutter/src/binding_wrapper.dart';
import 'package:ultra_flutter/ultra_flutter.dart';

class AppBinding extends WidgetsFlutterBinding
    with SentryWidgetsBindingMixin, UltraFlutterBinding {}

void main() {
  if (!kReleaseMode) {
    AppBinding();
  } else {
    WidgetsFlutterBinding.ensureInitialized();
  }
  // SentryFlutter.init(...) then runApp(...)
}

DevTools extension (optional)

For the live activity panel inside Flutter DevTools:

flutter pub add ultra_flutter_devtools

This adds a DevTools tab showing active sessions, recent tool calls, errors, and a screenshot grid.

Requirements

| Dependency | Version | Required | | ----------- | --------- | --------------------------------------------- | | Flutter SDK | >= 3.27.0 | Yes | | Dart SDK | >= 3.6.0 | Yes | | Node.js | >= 20 | Yes (plugin runtime) | | Claude Code | latest | Yes | | ffmpeg | any | Optional — video/GIF recording and conversion | | Android SDK | any | Optional — native mobile tools for Android | | Xcode | any | Optional — native mobile tools for iOS |

Platform support

| Capability | Web | Android | iOS | Windows | macOS | Linux | | -------------------- | :-: | :-----: | :------------: | :--------------: | :------------: | :------------: | | Build | x | x | x (macOS only) | x (Windows only) | x (macOS only) | x (Linux only) | | Runtime attach | x | x | x | x | x | x | | Gesture / screenshot | x | x | x | x | x | x | | Browser automation | x | - | - | - | - | - | | Native UI automation | - | x | x | x | x | x | | Patrol E2E tests | x | x | x | - | - | - | | DevTools panel | x | x | x | x | x | x |

Dart packages

ultra_flutter

In-app binding mixin that registers ext.flutter.ultra.* VM service extensions for gesture dispatch, screenshots, screencast streaming, widget matching, and log collection. The mixin form (on WidgetsBinding) composes with any existing binding — Sentry, Firebase, or custom subclasses.

SDK requirements: Flutter >= 3.27.0, Dart >= 3.6.0

ultra_flutter_devtools

Flutter DevTools extension that renders a live activity panel: active MCP sessions, recent tool calls with timing, error log, and a screenshot grid from tour/drive runs.

SDK requirements: Flutter >= 3.24.0, Dart >= 3.5.0

Development

git clone https://github.com/Bdaya-Dev/flutter-ultra-mcp.git
cd flutter-ultra-mcp
npm install
npm run build
npm test

The repo is a monorepo managed by Turborepo. Each server is a separate package under packages/. Dart packages live under dart/. Shared TypeScript utilities live under shared/.

packages/
  flutter-ultra-build/        # pubspec, codegen, tests, builds
  flutter-ultra-runtime/       # VM service, widget tree, performance
  flutter-ultra-gesture/       # tap, scroll, screenshot via mixin
  flutter-ultra-browser/       # Playwright web automation
  flutter-ultra-native-mobile/ # Android + iOS native
  flutter-ultra-native-desktop/# Windows + macOS + Linux native
  flutter-ultra-patrol/        # patrol_cli orchestration
  flutter-ultra-devtools/      # DevTools panel server
shared/
  mcp-runtime/                 # Shared server base, state, watchdog
dart/
  ultra_flutter/               # In-app binding mixin (pub.dev)
  ultra_flutter_devtools/      # DevTools extension (pub.dev)
skills/                        # Skill markdown files for Claude
examples/
  counter-app/                 # Minimal example
  oidc-app/                    # OIDC auth flow example

Available scripts

| Command | What it does | | ----------------------- | -------------------------------- | | npm run build | Build all packages via Turborepo | | npm run test | Run all unit tests | | npm run lint | Lint all packages | | npm run typecheck | TypeScript type checking | | npm run format | Format all files with Prettier | | npm run format:check | Check formatting without writing | | npm run test:e2e:web | End-to-end tests (web) | | npm run test:e2e:oidc | End-to-end tests (OIDC flow) |

Contributing

See CONTRIBUTING.md for the development workflow, commit message format, and local test instructions.

Security

See SECURITY.md for the loopback-only network design and vulnerability reporting process.

License

Apache-2.0 — see LICENSE.