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

It needs Python 3.10+ and adb — from Android Studio's SDK, or platform-tools.

pipx install flutter-bridge-mcp

pipx puts the server in its own virtualenv and the flutter-bridge-mcp executable on your PATH, which is what the MCP configs below expect. On Debian/Ubuntu, sudo apt install pipx && pipx ensurepath first.

A plain pip install works too, but on Debian, Ubuntu and recent Fedora it fails with error: externally-managed-environment — those distros forbid pip from writing into the system Python (PEP 668). Use pipx, or a virtualenv of your own:

python3 -m venv ~/.venvs/flutter-bridge
~/.venvs/flutter-bridge/bin/pip install flutter-bridge-mcp

Then point your MCP config at ~/.venvs/flutter-bridge/bin/flutter-bridge-mcp rather than the bare command. Do not reach for --break-system-packages; it writes into the Python your package manager owns.

From a clone, to hack on it:

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

The executable is then .venv/bin/flutter-bridge-mcp.

Tests

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

python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest

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

.venv/bin/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

If you installed into a virtualenv rather than with pipx, use that venv's absolute path in place of the bare flutter-bridge-mcp.

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.