Debug a Flutter App with AI on a Real Android Phone

To debug a Flutter app with AI, the agent needs the same evidence you use: what the screen shows, what the Dart runtime printed, and how Android sees the layout. ScreenSync MCP, a free Model Context Protocol (MCP) server for Android, gives an MCP client such as Claude Code all three from a real phone, so the agent can reproduce a bug, read the error, edit your Dart code and check the fix on the device.

What the agent needs to see

A Flutter bug usually leaves evidence in three places at once. The striped overflow marker is on the screen, the RenderFlex overflowed message is in the log, and the reason a button can't be found is in the semantics tree. An agent that only gets screenshots has to guess at the other two.

ScreenSync's own app is built with Flutter, so parts of the toolset speak Flutter: get_logcat exists to surface Dart errors, and the inspect_latest_mobile_screen prompt asks for the likely Flutter cause of each defect.

Of the hub's 226 MCP tools, most serve the browser extension; Flutter debugging on a phone uses about a dozen.

Set it up next to flutter run

If flutter run already deploys to your phone, most of the work is done: ScreenSync's control and log tools also use ADB.

1. Download the hub zip from the ScreenSync extension page, unzip it, and start it with start-hub.bat on Windows or sh start-hub.sh on macOS and Linux. It needs Node.js 18 or later and prints a pairing QR code.

2. Register the hub with your MCP client. In Claude Code it is one command:

   claude mcp add screensync node "<HUB_DIR>/screensync-hub.js"

   If you changed the hub's token from the default screensync-local-dev, give the server the same SCREEN_SYNC_TOKEN. Claude Desktop, Cursor and VS Code use the same node command and token in their own config files; the ScreenSync setup guide shows each layout.

3. Install the ScreenSync MCP app from Google Play (Android 7.0 or later), scan the QR code and accept Android's screen-capture prompt. The app then sends a frame to the hub over your own network each time you tap its floating bubble, or on a timer if you turn on Live mirror in its settings.

4. Run adb devices. If it lists more than one entry, such as an emulator and your phone, set SCREEN_SYNC_ADB_TARGET to the phone's serial so the hub drives the device Flutter deploys to. Flutter finds adb through the Android SDK, so if it is not on your PATH, point SCREEN_SYNC_ADB_BIN at it. Deploying over Wi-Fi works too; see Android wireless debugging for an MCP server.

5. Start the app with a plain flutter run, which builds in debug mode. Overflow warnings and assertion failures exist only in debug builds, so a release build hides much of what you want the agent to read.

Ask the agent to call control_status and get_device_status before anything else. The first confirms that ADB can reach the phone, which every control_* tool and get_logcat need. The second reports streaming when a phone frame has arrived in the last minute; if it says linked_no_frames, tap the bubble once.

Read Flutter errors from logcat

Flutter writes print and debugPrint output, plus the framework's error reports, to the Android log under the flutter tag. An uncaught asynchronous error shows up as an E/flutter line containing Unhandled Exception. get_logcat reads that log through ADB, so the agent gets the stack trace without you copying it out of a terminal.

The tool takes three arguments: pkg to keep only your app's process, grep for a case-insensitive text filter, and lines (10 to 2,000, default 200). Some typical calls:

get_logcat { "pkg": "com.example.shop", "grep": "flutter", "lines": 500 }
get_logcat { "grep": "overflowed", "lines": 1000 }
get_logcat { "grep": "FATAL EXCEPTION", "lines": 2000 }

Two details save time. First, the grep runs over the last lines lines of the log, not the whole buffer, so on a chatty device raise lines before deciding an error is missing. Second, pkg filters by the process ID your app has at the moment of the call. If Kotlin or Java code in a plugin crashes the app, the FATAL EXCEPTION belongs to the old process, and after a relaunch the filter hides it (if the app is not running, the filter is skipped entirely). For crashes, search without pkg. The Android logcat documentation explains the line format if you want to read raw output yourself.

Show the agent the tree Android sees

Flutter draws its own pixels, so Android has no native view for each widget. What get_ui_hierarchy returns, through uiautomator, is the accessibility tree that Flutter builds from its semantics. Each node carries its text, content description, resource ID, class, clickable flag, pixel bounds and center. The hub drops nodes that have no text and no description and are not clickable, treating them as noise.

That makes the hierarchy a rough accessibility report. An icon-only button without a tooltip shows up as an unlabeled clickable node. control_tap_text cannot find it, because it matches visible text and content descriptions, and a screen reader has nothing to announce either. One change fixes both:

IconButton(
  icon: const Icon(Icons.shopping_cart),
  tooltip: 'Open cart', // becomes the accessible label
  onPressed: openCart,
)

For stable test hooks, recent Flutter versions let the Semantics widget take an identifier, which Android reports as resource-id. A labeled, tappable element can then carry an ID that does not change with the locale; confirm it appears with get_ui_hierarchy before you rely on it. Custom painters with no semantics stay invisible to the tree, so for those the agent reads coordinates from a screenshot and uses control_tap. For more on this trade-off, read why your agent needs the Android UI hierarchy.

A debug loop that works

1. Reproduce. Give the agent the steps, or run the reproduce_bug prompt with a steps argument. That prompt tells the agent to take a control_screenshot before each step, act (preferring control_tap_text), check the result with compare_frames, and read get_logcat after the last step.

2. Collect evidence. A screenshot of the broken state, plus get_logcat filtered to your package. In debug builds the framework's error report usually names the widget that caused the problem, with a file and line in your lib folder.

3. Fix. In Claude Code the agent edits that file like any other code.

4. Reload. Press r in the flutter run terminal for a hot reload, or R for a hot restart. On macOS and Linux the agent can do this itself if you start Flutter with a PID file:

   flutter run --pid-file /tmp/flutter.pid
   kill -USR1 "$(cat /tmp/flutter.pid)"   # hot reload
   kill -USR2 "$(cat /tmp/flutter.pid)"   # hot restart

   Windows has no such signals, so there you press the key.

5. Verify. The agent takes a fresh control_screenshot of the same screen and compares it with the one from step 2, then runs get_logcat again to confirm the error line is gone. When timing matters, compare_frames grabs two ADB screenshots up to 10 seconds apart in one call and returns both with a coarse changedRatio. Treat that number as a hint that the screen changed, not as a pixel diff; the images are the proof.

To put the result on the phone, the agent can call publish_inspection to mark the bug regions and publish_patch to attach the diff. In the app's Diagnose tab, tap Fetch latest diagnosis to see the regions as a heatmap over your latest capture, with a Copy Git Patch button for the diff.

Bugs that hide at default settings

Some bugs only appear with a larger font, the on-screen keyboard, or a state that lasts half a second. Each deserves its own pass.

• Large text. Claude Code can run adb shell settings put system font_scale 1.3 from its shell, screenshot each screen, then set the scale back to 1.0. The accessibility_audit prompt checks for text likely to clip at larger sizes, unlabeled controls, low contrast and tap targets under 48 by 48 dp.
• The keyboard. Have the agent tap a text field, type with control_type, and take a screenshot. A submit button hidden behind the keyboard, or a form that overflows when the viewport shrinks, shows up at once.
• Brief states. A loading flash or a dialog that closes quickly usually falls between two screenshot calls, and Live mirror will not catch it either: it pushes one frame every few seconds, 1.5 seconds at the shortest. Use record_screen, which saves up to 15 seconds as an MP4 through ADB. The clip is solid evidence for you, but check whether your MCP client passes video to the model.

Performance is the exception. Debug builds do not show real frame timing, and screenshots cannot measure it. For jank, run flutter run --profile and use Flutter DevTools.

Limits worth knowing

• Android only. ScreenSync MCP does not support iOS, so bugs specific to the iOS build of your app need other tooling.
• Secure screens. If a screen sets FLAG_SECURE, Android blanks it in captures. Leave the flag off in debug builds if the agent needs to see that screen.
• Typed text is sanitized. control_type strips shell metacharacters such as quotes, backticks, $, &, |, ;, angle brackets, parentheses and braces before it sends text through ADB, so keep test input to plain characters.
• Screenshots reach your model provider. Frames travel from phone to hub over your own network with a bearer token and never reach EpsolDev servers, but any screenshot the agent reads goes to its model provider. Use test accounts and seeded data. The ScreenSync data policy lists where each piece of data is stored.

Next steps

Follow the setup guide to install the hub and pair your phone, then try one prompt on a screen you know is broken: "Take a screenshot, read logcat for my package, and tell me which widget overflows." If you want the wider picture of capture and control first, read what a screen MCP server is. ScreenSync MCP is free while in active development, at app 2.5.7 and hub 1.14.4 as of October 2026.