Flutter Skill
Control running Flutter applications for testing, debugging, and automation. Connects AI agents to Flutter apps via the Dart VM Service Protocol, exposing tools for UI inspection, gestures, state validation, screenshots, and log access.
Installation
Option 1: npx (Recommended)
{
"mcpServers": {
"flutter-skill": {
"command": "npx",
"args": ["flutter-skill"]
}
}
}
Option 2: Global Install
dart pub global activate flutter_skill
{
"mcpServers": {
"flutter-skill": {
"command": "flutter_skill",
"args": ["server"]
}
}
}
Key Tools
| Category |
Tools |
Purpose |
| Connection |
launch_app, connect_app |
Start or attach to a Flutter app |
| Inspection |
inspect, get_widget_tree, find_by_type |
Discover UI elements and widget structure |
| Interaction |
tap, enter_text, swipe, scroll_to, long_press, drag |
Perform gestures and input |
| Validation |
wait_for_element, wait_for_gone, get_text_value, get_checkbox_state |
Assert UI state |
| Screenshots |
screenshot, screenshot_element |
Capture visual state |
| Navigation |
go_back, get_current_route, get_navigation_stack |
Control and inspect navigation |
| Debug |
get_logs, get_errors, hot_reload, get_performance |
Diagnose issues |
Workflow
Core Testing Loop
launch_app(project_path: "/path/to/app")
→ screenshot()
→ inspect()
→ tap(key: "element_key") / enter_text(key: "field_key", text: "value")
→ screenshot()
→ verify with wait_for_element / get_text_value
Example: Login Flow
launch_app(project_path: "/path/to/app")
screenshot()
inspect()
enter_text(key: "email_field", text: "user@example.com")
enter_text(key: "password_field", text: "password123")
tap(key: "login_button")
wait_for_element(key: "home_screen", timeout: 5000)
screenshot()
If wait_for_element times out: Call screenshot() to see the current state, then get_errors() to check for crashes or failed network requests.
Example: Debug a Running App
connect_app(uri: "ws://127.0.0.1:50000/ws")
get_errors()
get_logs()
screenshot()
inspect()
Validation Checkpoints
- After
launch_app(): Verify a VM Service URI was returned. If not, check that Flutter is installed and the app compiles.
- After
inspect(): Confirm interactive elements are returned. If empty, the app may still be loading — call screenshot() and retry.
- After gestures (
tap, enter_text, swipe): Call screenshot() to confirm the UI updated as expected.
- After navigation: Use
wait_for_element(key: "target") with a timeout. On timeout, call get_errors() to diagnose.
Element Targeting Priority
key: (most reliable) — widget key set by the developer via ValueKeytext: — visible text content (breaks if text changes)type: — widget type via find_by_type (may match multiple elements)
For reliable targeting, apps should use ValueKey on interactive elements:
ElevatedButton(
key: const ValueKey('submit_button'),
onPressed: _submit,
child: const Text('Submit'),
)
Links
1---2name: flutter-skill3description: Automate and test Flutter applications — launch apps, inspect widgets, tap elements, enter text, scroll, swipe, take screenshots, validate state, and debug via Dart VM Service Protocol. Use when the user wants to run Flutter app tests, automate Flutter UI interactions, inspect widget trees, debug a running Flutter app, or perform gesture-based testing.4---56# Flutter Skill78Control running Flutter applications for testing, debugging, and automation. Connects AI agents to Flutter apps via the Dart VM Service Protocol, exposing tools for UI inspection, gestures, state validation, screenshots, and log access.910## Installation1112### Option 1: npx (Recommended)13```json14{15 "mcpServers": {16 "flutter-skill": {17 "command": "npx",18 "args": ["flutter-skill"]19 }20 }21}22```2324### Option 2: Global Install25```bash26dart pub global activate flutter_skill27```2829```json30{31 "mcpServers": {32 "flutter-skill": {33 "command": "flutter_skill",34 "args": ["server"]35 }36 }37}38```3940## Key Tools4142| Category | Tools | Purpose |43|----------|-------|---------|44| **Connection** | `launch_app`, `connect_app` | Start or attach to a Flutter app |45| **Inspection** | `inspect`, `get_widget_tree`, `find_by_type` | Discover UI elements and widget structure |46| **Interaction** | `tap`, `enter_text`, `swipe`, `scroll_to`, `long_press`, `drag` | Perform gestures and input |47| **Validation** | `wait_for_element`, `wait_for_gone`, `get_text_value`, `get_checkbox_state` | Assert UI state |48| **Screenshots** | `screenshot`, `screenshot_element` | Capture visual state |49| **Navigation** | `go_back`, `get_current_route`, `get_navigation_stack` | Control and inspect navigation |50| **Debug** | `get_logs`, `get_errors`, `hot_reload`, `get_performance` | Diagnose issues |5152## Workflow5354### Core Testing Loop5556```57launch_app(project_path: "/path/to/app")58 → screenshot()59 → inspect()60 → tap(key: "element_key") / enter_text(key: "field_key", text: "value")61 → screenshot()62 → verify with wait_for_element / get_text_value63```6465### Example: Login Flow6667```68launch_app(project_path: "/path/to/app")69screenshot()70inspect()71enter_text(key: "email_field", text: "user@example.com")72enter_text(key: "password_field", text: "password123")73tap(key: "login_button")74wait_for_element(key: "home_screen", timeout: 5000)75screenshot()76```7778**If `wait_for_element` times out:** Call `screenshot()` to see the current state, then `get_errors()` to check for crashes or failed network requests.7980### Example: Debug a Running App8182```83connect_app(uri: "ws://127.0.0.1:50000/ws")84get_errors()85get_logs()86screenshot()87inspect()88```8990## Validation Checkpoints9192- **After `launch_app()`**: Verify a VM Service URI was returned. If not, check that Flutter is installed and the app compiles.93- **After `inspect()`**: Confirm interactive elements are returned. If empty, the app may still be loading — call `screenshot()` and retry.94- **After gestures** (`tap`, `enter_text`, `swipe`): Call `screenshot()` to confirm the UI updated as expected.95- **After navigation**: Use `wait_for_element(key: "target")` with a timeout. On timeout, call `get_errors()` to diagnose.9697## Element Targeting Priority98991. **`key:`** (most reliable) — widget key set by the developer via `ValueKey`1002. **`text:`** — visible text content (breaks if text changes)1013. **`type:`** — widget type via `find_by_type` (may match multiple elements)102103For reliable targeting, apps should use `ValueKey` on interactive elements:104```dart105ElevatedButton(106 key: const ValueKey('submit_button'),107 onPressed: _submit,108 child: const Text('Submit'),109)110```111112## Links113114- [GitHub Repository](https://github.com/ai-dashboad/flutter-skill)115- [pub.dev Package](https://pub.dev/packages/flutter_skill)116- [npm Package](https://www.npmjs.com/package/flutter-skill)
ai-dashboad