Flutter Skill

Give your AI Agent eyes and hands inside your Flutter app.

Version npm License Platform

Flutter Skill is a bridge that connects AI Agents (like Claude Code, Cursor, Windsurf) directly to running Flutter applications via the MCP (Model Context Protocol). It provides 30+ tools for UI automation, inspection, and testing.

Quick Start

1. Install

⚡ One-Click Install (Recommended)

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/ai-dashboad/flutter-skill/main/install.sh | bash

# Windows PowerShell (Run as Administrator)
iwr https://raw.githubusercontent.com/ai-dashboad/flutter-skill/main/install.ps1 -useb | iex

Or Manual Install:

# npm (recommended - includes native binary for instant startup)
npm install -g flutter-skill-mcp

# Homebrew (macOS/Linux)
brew tap ai-dashboad/flutter-skill
brew install flutter-skill

# Scoop (Windows)
scoop bucket add flutter-skill https://github.com/ai-dashboad/scoop-flutter-skill
scoop install flutter-skill

# Dart (requires Flutter SDK)
dart pub global activate flutter_skill

# IDE Extensions
# - VSCode: Search "Flutter Skill" in Extensions
# - IntelliJ/Android Studio: Search "Flutter Skill" in Plugins

What does one-click install do?

  • ✅ Auto-detects best installation method (npm > Homebrew/Scoop > source)
  • ✅ Auto-installs tool priority rules to ~/.claude/prompts/
  • ✅ Auto-configures PATH environment variable
  • ✅ Resolves all dependencies and version issues
  • ✅ Cross-platform support (macOS, Linux, Windows)

2. Configure AI Agent

Add to your AI agent's MCP config:

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "flutter-skill": {
      "command": "flutter-skill",
      "args": ["server"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "flutter-skill": {
      "command": "flutter-skill",
      "args": ["server"]
    }
  }
}

One command to ensure Claude always uses flutter-skill for Flutter testing:

flutter_skill setup

This installs priority rules that ensure Claude Code ALWAYS uses flutter-skill instead of Dart MCP for Flutter testing, giving you 100% UI automation capability.

What it does:

  • ✅ Installs rules to ~/.claude/prompts/
  • ✅ Claude Code automatically prioritizes flutter-skill for ALL Flutter testing
  • ✅ Adds --vm-service-port=50000 flag automatically (Flutter 3.x compatibility)
  • ✅ No manual tool selection needed

First-time run auto-reminder: When you run any flutter_skill command for the first time, you'll see a reminder if the rules aren't installed yet.

See also: Tool Priority Setup Guide

4. Use

// Option 1: Launch app with environment variables
flutter-skill.launch_app({
  project_path: "/path/to/flutter/project",
  dart_defines: ["ENV=staging", "DEBUG=true"],
  flavor: "staging"
})

// Option 2: Connect to already running app (auto-detect)
flutter-skill.scan_and_connect()

// Now use any tool
flutter-skill.screenshot()
flutter-skill.tap({ text: "Login" })
flutter-skill.inspect()

Features

App Lifecycle Management

Tool Description
launch_app Launch Flutter app with dart_defines, flavor, target, extra_args
scan_and_connect Auto-scan ports and connect to first running Flutter app
list_running_apps List all running Flutter apps (VM Services)
connect_app Connect to specific VM Service URI
stop_app Stop the currently running app
disconnect Disconnect without stopping the app
get_connection_status Get connection info and suggestions
hot_reload Fast reload (keeps state)
hot_restart Full restart (resets state)

UI Inspection

Tool Description
inspect Get interactive elements with coordinates, size, and center point
get_widget_tree Get widget tree structure with depth control
get_widget_properties Get properties of a widget (size, position, visibility)
get_text_content Extract all visible text from the screen
find_by_type Find widgets by type (e.g., ElevatedButton)

Interactions

Tool Description
tap Tap a widget by Key or Text (returns success/failure)
double_tap Double tap a widget
long_press Long press with configurable duration
swipe Swipe gesture (up/down/left/right)
edge_swipe Swipe from screen edge (for drawer menus, back gestures)
drag Drag from one element to another
scroll_to Scroll to make an element visible
enter_text Enter text into a text field (returns success/failure)

State & Validation

Tool Description
get_text_value Get current value of a text field
get_checkbox_state Get checked state of a checkbox/switch
get_slider_value Get current value of a slider
wait_for_element Wait for an element to appear (with timeout)
wait_for_gone Wait for an element to disappear

Screenshots

Tool Description
screenshot Take full app screenshot (quality, max_width options)
screenshot_region Take screenshot of specific region (x, y, width, height)
screenshot_element Take screenshot of specific element
Tool Description
get_current_route Get the current route name
go_back Navigate back
get_navigation_stack Get the navigation stack

Debug & Logs

Tool Description
get_logs Get application logs
get_errors Get application errors
clear_logs Clear logs and errors
get_performance Get performance metrics

Utilities

Tool Description
pub_search Search Flutter packages on pub.dev

Installation Methods

Method Command Platform
npm npm install -g flutter-skill-mcp All
Homebrew brew install ai-dashboad/flutter-skill/flutter-skill macOS/Linux
Docker docker pull ghcr.io/ai-dashboad/flutter-skill All
Snap snap install flutter-skill Linux
Scoop scoop install flutter-skill Windows
Winget winget install AIDashboard.FlutterSkill Windows
pub.dev dart pub global activate flutter_skill All
VSCode Extensions → "Flutter Skill" All
IntelliJ Plugins → "Flutter Skill" All
Devcontainer See below All

Docker

# Run MCP server
docker run --rm -it ghcr.io/ai-dashboad/flutter-skill server

# Or use in docker-compose
services:
  flutter-skill:
    image: ghcr.io/ai-dashboad/flutter-skill:latest
    command: ["server"]

Devcontainer Feature

Add to your .devcontainer/devcontainer.json:

{
    "features": {
        "ghcr.io/ai-dashboad/flutter-skill/flutter-skill:latest": {}
    }
}

Native Binary Performance

Version Startup Time
Dart JIT ~1 second
Native Binary ~0.01 second

Native binaries are automatically downloaded on first use for supported platforms:

  • macOS (Apple Silicon & Intel)
  • Linux (x64)
  • Windows (x64)

Flutter App Setup

For the MCP tools to work, your Flutter app needs the flutter_skill package:

flutter-skill launch /path/to/project
# Automatically adds dependency and initializes

Manual Setup

  1. Add dependency:
dependencies:
  flutter_skill: ^0.5.1
  1. Initialize in main.dart:
import 'package:flutter_skill/flutter_skill.dart';

void main() {
  FlutterSkillBinding.ensureInitialized();
  runApp(MyApp());
}

Example Workflows

E2E Testing with Environment Variables

// Launch staging environment
flutter-skill.launch_app({
  project_path: "./",
  dart_defines: ["ENV=staging", "API_URL=https://staging.api.com"],
  flavor: "staging",
  target: "lib/main_staging.dart"
})

// Wait for app to load
flutter-skill.wait_for_element({ text: "Welcome" })

// Take screenshot
flutter-skill.screenshot()

// Perform login
flutter-skill.tap({ text: "Login" })
flutter-skill.enter_text({ key: "email_field", text: "test@example.com" })
flutter-skill.enter_text({ key: "password_field", text: "password123" })
flutter-skill.tap({ text: "Submit" })

// Verify success
flutter-skill.wait_for_element({ text: "Dashboard" })

Connect to Running App

// List all running Flutter apps
flutter-skill.list_running_apps()
// Returns: { apps: ["ws://127.0.0.1:50123/ws", ...], count: 2 }

// Auto-connect to first one
flutter-skill.scan_and_connect()

// Or connect to specific one
flutter-skill.connect_app({ uri: "ws://127.0.0.1:50123/ws" })

Debug a UI Issue

// Get widget tree
flutter-skill.get_widget_tree({ max_depth: 5 })

// Find specific widgets
flutter-skill.find_by_type({ type: "ElevatedButton" })

// Inspect interactive elements
flutter-skill.inspect()

// Check if element is visible
flutter-skill.wait_for_element({ key: "submit_button", timeout: 3000 })

IDE Extensions

VSCode Extension

  • Auto-detects Flutter projects
  • Prompts to add flutter_skill dependency
  • Auto-downloads native binary
  • Status bar shows connection state
  • Commands: Launch, Inspect, Screenshot

IntelliJ/Android Studio Plugin

  • Same features as VSCode
  • Integrates with IDE notifications
  • Tool window for status

Troubleshooting

"Not connected to Flutter app"

// Check status and get suggestions
flutter-skill.get_connection_status()

// This returns:
// - Current connection state
// - List of available apps
// - Actionable suggestions

"Unknown method ext.flutter.flutter_skill.xxx"

Your Flutter app doesn't have the flutter_skill package. Add it:

flutter pub add flutter_skill

Then restart the app (hot reload is not enough).

MCP server slow to start

The native binary should auto-download. If not:

# For npm
npm update -g flutter-skill-mcp

# For Homebrew
brew upgrade flutter-skill

📚 Documentation

Core Documentation

Research & Deep Dives

Release Notes

License

MIT

Libraries

flutter_skill