flutter-ultra-mcp

A Claude Code plugin that gives your AI agent full control over Flutter apps across all platforms. 8 isolated MCP servers, 248 tools, 2 Dart packages, and 12 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 | 96 | Pub dependencies, code generation, analysis, formatting, tests, platform builds, l10n, assets, signing | | flutter-ultra-runtime | 55 | Attach to debug sessions, widget tree inspection, performance profiling, design audit, logs, HTTP capture | | flutter-ultra-browser | 26 | Playwright-driven web automation — OAuth flows, popups, console, network, storage, JS evaluation | | flutter-ultra-native-mobile | 24 | Android (UIAutomator) + iOS (XCUITest) — permissions, OAuth tabs, accessibility tree, device recording | | flutter-ultra-gesture | 18 | Tap, swipe, scroll, text input, screenshots, screencast via the in-app ultra_flutter mixin | | flutter-ultra-patrol | 15 | 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 | | flutter-ultra-devtools | 5 | Live MCP activity panel inside Flutter DevTools — sessions, tool calls, errors, screenshot grid | | Total | 248 | |

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>.

| 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 |

Installation

Plugin (required)

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

This registers all 8 MCP servers and 12 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.