Flutter Skill

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

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

⚡ 一键安装（推荐）

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

# Windows PowerShell (管理员权限)
iwr https://raw.githubusercontent.com/ai-dashboad/flutter-skill/main/install.ps1 -useb | iex

或手动安装：

# 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 (需要 Flutter SDK)
dart pub global activate flutter_skill

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

一键安装做了什么？

• ✅ 自动检测最佳安装方法（npm > Homebrew/Scoop > 源码）
• ✅ 自动安装工具优先级规则到 ~/.claude/prompts/
• ✅ 自动配置 PATH 环境变量
• ✅ 解决所有依赖和版本问题
• ✅ 跨平台支持（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"]
    }
  }
}

3. Setup Tool Priority (Recommended for Claude Code)

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

UI Inspection

Interactions

State & Validation

Screenshots

Navigation

Debug & Logs

Utilities

Installation Methods

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

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:

Automatic Setup (Recommended)

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

Manual Setup

1. Add dependency:

dependencies:
  flutter_skill: ^0.4.4

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

• Usage Guide - Detailed usage instructions
• Architecture - System architecture and communication flow
• Troubleshooting - Common issues and solutions
• Flutter 3.x Fix - Flutter 3.x compatibility guide

Research & Deep Dives

• DTD Protocol Research - DTD vs VM Service analysis
• Communication Flow - Complete communication flow examples
• Protocol Details - DTD protocol specifications

Release Notes

• v0.3.2 Auto VM Service - Auto-configuration feature

Links

• GitHub
• pub.dev
• npm
• VSCode Marketplace
• JetBrains Marketplace

License

MIT