Flutter Mobile Debugging

Flutter Mobile Debugging via Mobile MCP + ADB/simctl

Overview

Workflow for debugging Flutter apps on real Android devices and iOS Simulators using the Mobile MCP tool suite, adb, and xcrun simctl. Covers the full cycle: build → install → launch → interact → capture → analyze logs.

Prerequisites

• Android: Device connected via USB with adb accessible
• iOS: Simulator booted via Xcode or xcrun simctl boot
• Get device ID: mcp mobile_list_available_devices, adb devices, or xcrun simctl list devices booted
• Flutter project buildable with flutter build apk --debug or flutter build ios --simulator --debug

Core Workflow

1. Build and Install

Android:

flutter build apk --debug 2>&1 | tail -3
adb -s DEVICE_ID install -r build/app/outputs/flutter-apk/app-debug.apk

iOS Simulator:

flutter build ios --simulator --debug 2>&1 | tail -5
xcrun simctl install  build/ios/iphonesimulator/Runner.app

> ⚠️ Do NOT use flutter run if it hangs. flutter run calls xcdevice list which > can freeze indefinitely when real iOS devices are connected. The build+simctl approach > bypasses this entirely. See [Troubleshooting](#flutter-run-hangs-on-ios) below.

2. Launch App

Android — direct launch:

adb -s DEVICE_ID shell am start -n com.example.app/.MainActivity

Android — share intent:

adb -s DEVICE_ID shell am start -a android.intent.action.SEND \
  -t text/plain \
  --es android.intent.extra.TEXT "https://example.com" \
  -n com.example.app/.MainActivity

Android — force-stop:

adb -s DEVICE_ID shell am force-stop com.example.app

iOS Simulator — launch:

xcrun simctl launch  
# Example: xcrun simctl launch 65115B75-... com.example.yourapp

iOS Simulator — terminate:

xcrun simctl terminate  

3. Wait for UI to Settle

AI operations, network fetches, and animations need time:

sleep 10  # Adjust based on expected operation time

4. Interact with UI

Discover elements:

mcp mobile_list_elements_on_screen(device=DEVICE_ID)

Returns element types, text, labels, and coordinates — use coordinates for clicking.

Click:

mcp mobile_click_on_screen_at_coordinates(device=DEVICE_ID, x=872, y=2026)

Swipe (scroll):

mcp mobile_swipe_on_screen(device=DEVICE_ID, direction="up", distance=500)

Type text:

mcp mobile_type_keys(device=DEVICE_ID, text="hello", submit=false)

5. Capture and Analyze

Screenshot:

mcp mobile_take_screenshot(device=DEVICE_ID)          # View inline
mcp mobile_save_screenshot(device=DEVICE_ID, saveTo=path)  # Save to file

Logcat (Flutter logs):

# All flutter logs
adb -s DEVICE_ID logcat -d | grep "I flutter" | tail -30

# Clear log buffer before test
adb -s DEVICE_ID logcat -c

Critical Tips

print() vs debugPrint() for Logcat

Always use print() when debugging via logcat, not debugPrint().

debugPrint() throttles output to avoid flooding the console. On real devices, this throttling can cause messages to never appear in adb logcat. print() outputs reliably.

// BAD — may not appear in logcat
debugPrint('[MyWidget] state changed to $value');

// GOOD — always appears in logcat
print('[MyWidget] state changed to $value');

Logcat Filter Patterns

# Flutter only (tag-based filter)
adb -s DEVICE_ID logcat -d -s flutter

# Grep-based (more flexible)
adb -s DEVICE_ID logcat -d | grep "I flutter"

# Custom marker (recommended for targeted debugging)
adb -s DEVICE_ID logcat -d | grep "\[MyWidget\]"

Full Test Cycle Command Chain

Combine steps for efficient single-command testing:

# Build, install, clear logs, force-stop, launch, wait, capture logs
flutter build apk --debug 2>&1 | tail -3 && \
adb -s DEVICE_ID install -r build/app/outputs/flutter-apk/app-debug.apk && \
adb -s DEVICE_ID logcat -c && \
adb -s DEVICE_ID shell am force-stop com.example.app && \
sleep 1 && \
adb -s DEVICE_ID shell am start -n com.example.app/.MainActivity && \
sleep 10 && \
adb -s DEVICE_ID logcat -d | grep "I flutter"

Element Coordinates

mobile_list_elements_on_screen returns coordinates with x, y, width, height. Click the center of the element:

• Click X = coordinates.x + coordinates.width / 2
• Click Y = coordinates.y + coordinates.height / 2

Debug Print Cleanup

After debugging, always remove all print() statements before committing. Search for leftover prints:

grep -rn "print(" lib/ --include="*.dart" | grep -v "// " | grep -v "debugPrint"

Troubleshooting

flutter run Hangs on iOS {#flutter-run-hangs-on-ios}

Symptom: flutter run -d hangs with no output for minutes.

Root cause: flutter run calls xcdevice list --timeout 5 which freezes when real iOS devices are connected (known Flutter/Xcode issue).

Diagnosis:

ps aux | grep xcdevice          # Stuck xcdevice list processes
ps aux | grep flutter_tools.snapshot | wc -l  # Multiple = zombie daemons

Fix:

# 1. Kill stuck processes
pkill -9 -f "flutter_tools.snapshot"
pkill -9 -f "xcdevice"

# 2. Use build + simctl install instead
flutter build ios --simulator --debug
xcrun simctl install  build/ios/iphonesimulator/Runner.app
xcrun simctl launch  

Prevention: Disconnect real iOS devices when targeting simulator only.

Related skills

• systematic-debugging — use first to identify which layer the bug lives in (Dart, native, bridge). Flutter-mobile-debugging is the concrete tool chain for attaching debuggers and inspecting native code.
• root-cause-tracing — use to trace through call stacks before attaching debuggers. Narrow down the exact location, then use native debuggers from this skill.
• flutter-verify — after fixing using native debugger, verify the fix works on the exact device/OS where it crashed.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ImL1s
• Source: ImL1s/flutter-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.