Flutter Agent Lens MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to running Flutter applications. It communicates with the Dart VM Service over WebSockets, giving AI tools direct access to application state, performance data, layout constraints, and console logs.

---

Features

AI assistants (such as Claude or Copilot) can inspect, profile, and debug any Flutter application running in debug or profile mode. You can use this server to:

• Track widget rebuild frequencies.
• Diagnose rendering bottlenecks and frame jank.
• Analyze CPU usage and execution hotspots.
• Audit memory usage and find retaining paths that cause memory leaks.
• Capture console, stdout, stderr, and logging streams.
• Read local build sizes to locate heavy packages and assets.
• Validate App Links and Universal Links configurations.
• Drive scroll behaviors and trigger hot reloads.

---

Requirements

• Dart SDK / Flutter SDK (installed and added to the system PATH).
• A Flutter application running in debug or profile mode.

---

Setup

1. Install the CLI

Activate the package globally to register the flutter-agent-lens binary:

dart pub global activate flutter_agent_lens

Ensure your global pub cache bin directory is in your system PATH (typically ~/.pub-cache/bin on macOS/Linux or %USERPROFILE%\AppData\Local\Pub\Cache\bin on Windows).

2. Configure the MCP Host

Add the server details to the configuration file of your MCP client host:

Claude Desktop

Add the following to your configuration file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "flutter_agent_lens": {
      "command": "flutter-agent-lens"
    }
  }
}

Cursor

1. Go to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Set the configuration:
   • Name: flutter_agent_lens
   • Type: command
   • Command: flutter-agent-lens

---

Tool Catalog

All tools require an active connection to a running application, unless stated otherwise.

Connection and Discovery

Tool Name	Parameters	Description
connect_to_app / connect	uri (required, or vmServiceUri for alias), workspace_root (optional)	Connect to a running Flutter application via its VM Service URI.
list_running_apps	None	Scan for running Flutter VM Service ports on the host.
autodiscover_app / discover_apps	workspace_root (optional)	Scan active OS processes and connect automatically if exactly one application is running.
disconnect	None	Disconnect from the currently active application.
get_app_info	None	Retrieve VM metadata, isolates, platform details, and active extension RPCs.

Performance and Build

Tool Name	Parameters	Description
diagnose_jank	duration_seconds (default: 3)	Analyze frame render times and highlight frames exceeding the 16.6ms budget.
get_cpu_profile	duration_seconds (default: 3)	Sample CPU ticks to identify performance hotspots in Dart functions.
get_widget_rebuild_counts	duration_seconds (default: 3)	Track widget rebuild counts to identify unnecessary layout updates.
hot_reload	None	Trigger a hot reload on the connected main isolate.
hot_restart	None	Trigger a hot restart of the running application.
analyze_bundle_size	build_target (default: 'apk')	Parse local code-size-details.json maps to find bloated packages.

Layout Inspection

Tool Name	Parameters	Description
get_widget_tree	maxDepth (optional, default: 15), projectOnly (optional, default: false)	Retrieve the structured widget tree of the running Flutter application.
inspect_layout_constraints / inspect_widget	widget_id (required, or widgetId for alias)	Inspect parent

... View full README on GitHub