Flutter Lamp

💡 Flutter Lamp

Give your AI live eyes on a running Flutter app — no more pasting logs.

An MCP server that connects Claude Code, Claude Desktop, Cursor, Codex & Gemini directly to a running Flutter app through the Dart VM Service Protocol — streaming exceptions, logs, network calls, frame timings and memory as structured data, plus an evidence-first root-cause diagnosis engine and a live browser dashboard.

---

Why

Today you debug Flutter with your AI by copy-pasting stack traces, flutter run output and DevTools screenshots. The AI is blind between messages.

Flutter Lamp makes the AI runtime-aware. It reads the app's live state over official Flutter/Dart APIs (never scraping DevTools), so instead of *"paste the error"* the AI can ask the app *"what just happened, and why?"*

❌  You: *pastes 40 lines of red stack trace*

✅ AI: connect_vm → get_exceptions → diagnose_runtime → "RenderFlex overflow in Column at home.dart:42, triggered right after GET /api/user returned 500. Confidence 85%. Fix: …"

Features

• 🔌 One-line connect to any running Flutter app's VM Service
• 💥 Realtime exceptions with reconstructed stack traces (framework + unhandled)
• 📝 Console & structured logs (Stdout / Stderr / dart:developer)
• 🌐 Network capture via dart:io profiling — covers Dio & package:http, no interceptor needed
• 🎞️ Frame timings with jank detection, percentiles, and a build-vs-raster verdict
• 🧭 Route awareness — current screen, transitions, and failures attributed to the screen they happened on
• 🧠 State-management activity — Riverpod, Provider and Bloc churn correlated with rebuild storms
• 🔁 Widget rebuild attribution — which widget rebuilt, how often, at which file and line, with your code ranked apart from package code
• 🧬 Widget tree & selected-widget snapshots from the Inspector
• 🧮 Memory (Dart heap / external) and VM timeline events
• 🩺 `diagnose_runtime` — correlates evidence into *summary · root cause · evidence · confidence · fixes*; says "Unknown" below 70% instead of hallucinating
• 📊 Live browser dashboard at http://127.0.0.1:7373 — streams everything over WebSocket, independent of the AI connection
• 🧩 Ships a reusable `flutter-runtime-diagnosis` Claude Code skill

Tools

mutates means the tool changes app or VM state, not your project — nothing here writes code or files. connect_vm enables dart:io HTTP timeline logging on the app so network capture works; get_timeline with recordFrom: true changes the VM's recording flags. Every tool carries an MCP readOnlyHint annotation so a client can enforce this itself.

Agents should not call all of them. The recommended flow is runtime_health → what_changed → a targeted get_* → diagnose_runtime; see AI Agent Integration.

Install

Requires Node ≥ 20. Nothing to clone — npx fetches it on first run:

npx -y flutter-lamp

Or install it globally:

npm install -g flutter-lamp

From source

git clone https://github.com/itsonu/flutter-lamp.git

cd flutter-lamp npm install npm run build node dist/index.js

Connect your AI client

Claude Code plugin (recommended) — installs the MCP server *and* the flutter-runtime-diagnosis skill in one step:

/plugin marketplace add itsonu/flutter-lamp

/plugin install flutter-lamp@flutter-lamp

The plugin pins an exact, published server version. Flutter Lamp is also listed in the MCP Registry as io.github.itsonu/flutter-lamp.

Or add the server to your MCP client config yourself, then restart the client.

Claude Code — .mcp.json in your project:

{

"mcpServers": { "flutter-lamp": { "command": "npx", "args": ["-y", "flutter-lamp"] } } }

Or from the CLI:

claude mcp add --scope user flutter-lamp -- npx -y flutter-lamp

--scope user makes it available in every project; drop it to register for the current project only.

Cursor (~/.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json) use the same mcpServers shape.

Running from a clone instead? Point command at node and args at /absolute/path/to/flutter-lamp/dist/index.js.

Optional environment variables:

Usage

1. Run your Flutter app in debug/profile mode:

   flutter run

Copy the line it prints:

   A Dart VM Service on <device> is available at: http://127.0.0.1:PORT/TOKEN=/

Tip: flutter run --vm-service-port=8181 gives a stable URI across restarts.

1. Ask your AI to connect and diagnose — e.g. *"connect to my Flutter app at and tell me why it's throwing."* With the bundled skill, Claude Code runs the whole flow (connect → gather → diagnose_runtime) automatically and never asks you to paste logs when the VM Service is reachable.

1. Open http://127.0.0.1:7373 in a browser for the live dashboard — it runs alongside the AI, not instead of it.

Debugging without a cable (Android)

A flutter run started over USB loses its VM Service tunnel the moment the cable moves; one started over a TCP transport does not. Ask the server which transports exist:

ensure_tcp_device                  # read-only: lists transports, recommends one

ensure_tcp_device { promote: true } # puts a USB-only device on TCP (needs the cable once)

Then launch against the wireless serial it recommends:

flutter run -d 192.168.88.3:5555

The cable is only needed for the one-time promotion. Reverse it any time with adb usb.

Live dashboard

A zero-dependency dark UI (native HTTP + WebSocket, no build step) that streams runtime data as it happens:

Overview — a session report: health, FPS, memory, worst frame, MCP activity, and findings that link through to the events behind them (the worst-frame finding opens the timeline filtered to that frame) · Logs (search / filter / auto-scroll) · Network (expandable headers & timing) · Exceptions (expandable stack traces) · Timeline · Performance (live canvas charts) · MCP — which agent connected, every tool it called, with latency, errors and response size · Inspector — which inspection links exist and which are pull-only · Diagnostics — the measured topology, per-collector health, and what this target cannot observe at all.

Controls: pause/resume · clear view · export JSON · per-tab search · auto-reconnect.

The UI distinguishes states that look alike and are not: 0 MB is a measurement, not sampled yet is the absence of one, and an empty tab says whether a filter is hiding rows, the collector is blind on this target, or the collector is watching and has seen nothing. Readings taken before a disconnect are labelled as such rather than left looking live.

How it works

Running Flutter app

│ Dart VM Service Protocol (JSON-RPC over WebSocket) ▼ VmService client ──▶ Collectors (log · exception · frame · network · …) │ ▼ RuntimeStore (one centralized, capped event stream; every event: timestamp · source · severity · category) │ │ ┌──────────┘ └──────────┐ ▼ ▼ MCP tools (stdio) Dashboard (HTTP + WebSocket) → Claude Code / Cursor / … → your browser

Everything flows through one event store. Adding a new runtime source = implement the Collector interface and register it — no other layer changes. Design principles: official Flutter/Dart APIs only, structured JSON over text, never scrape DevTools, and never claim a cause the evidence doesn't support.

Limitations

• Debug/profile builds only. The VM Service, Inspector and dart:io HTTP profiling are not available in release builds.
• Network is pull-on-demand. Dart exposes no push stream for dart:io HTTP, so requests are fetched when get_network or diagnose_runtime runs — not streamed continuously.
• Exceptions are not always observable. Debug.PauseException needs pause-on-exception enabled in the app to fire. Flutter.Error is posted by the widget inspector only while structured error reporting is on, which the framework disables in profile mode and on the web