flutter-bridge-mcp

Your Android tools see a Flutter app as one opaque rectangle. This makes that rectangle readable. Point at wrong-looking text on screen and get back the file and line that built it, edit it, hot reload, then diff the pixels to prove only that changed.

It also does the Android basics — logcat, crashes, taps, screenshots — filtered and truncated server-side so a response can never blow up the model's context.

Tools

Reading logs

Driving the device

Flutter ↔ Android bridge

Android tooling sees a Flutter app as one opaque SurfaceView; Dart tooling sees widgets but knows nothing about logcat, ANRs or native crashes. These join the two.

The loop

The point of the bridge is this cycle, which no other Android or Flutter MCP closes:

screenshot          see the bug
flutter_locate      -> "Total Patients" at (410,269), built by
                       lib/presentation/dashboard/widgets/dashboard_grid.dart:76
ui_checkpoint       remember the screen
<edit that line>
flutter_hot_reload  apply it
ui_diff             confirm exactly what changed, and nothing else

ui_diff reports the percentage of pixels that changed, clusters them into regions, and returns the screen with those regions outlined — so "did my fix land, and did it disturb anything else?" is answered rather than eyeballed.

Requires a debug or profile build. The VM Service URI is printed to logcat only at launch, so if it has scrolled away use flutter_connect(package=..., relaunch=True).

Prefer ui_dump and tap(text=...) over screenshots and raw coordinates: it is far cheaper, and it does not break when the layout or resolution changes. Screenshots are downscaled, so coordinates read off one are not device coordinates.

There is deliberately no arbitrary adb shell tool.

Install

pip install flutter-bridge-mcp

Or from a clone, to hack on it:

python3 -m venv .venv
.venv/bin/pip install -e .

Either way you get a flutter-bridge-mcp executable on the path (in .venv/bin/ for the editable install). It needs Python 3.10+ and adb — from Android Studio's SDK, or platform-tools.

Tests

The unit suite covers log parsing, error grouping and widget-tree flattening, and needs no device:

pip install -e ".[test]"
python -m pytest

selftest.py is the other half — it exercises the real thing against an attached device:

python selftest.py --package com.example.app --project ~/StudioProjects/app

Without --package it checks the Android side only; --project adds hot reload.

Use in Claude Code (including the Claude plugin in Android Studio)

The Studio plugin reads the Claude Code CLI config, so registering it once covers both:

claude mcp add flutter-bridge flutter-bridge-mcp \
  -e ADB_PATH=/abs/path/to/Android/Sdk/platform-tools/adb

Use with Gemini in Android Studio

Create mcp.json in the Studio config directory (~/.config/Google/AndroidStudio<version>/mcp.json on Linux, ~/Library/Application Support/Google/AndroidStudio<version>/ on macOS):

{
  "mcpServers": {
    "flutter-bridge": {
      "command": "/abs/path/to/flutter-bridge-mcp",
      "args": [],
      "env": { "ADB_PATH": "/abs/path/to/Android/Sdk/platform-tools/adb" }
    }
  }
}

Restart Studio, then in Gemini → Agent mode check the tools menu for flutter-bridge.

Configuration

License

MIT — see LICENSE.