flutter-dev-mcp

An MCP (Model Context Protocol) server that gives AI coding agents first-class Flutter development tools.

Why?

Flutter CLI tools are designed for humans, not agents. flutter test dumps hundreds of lines of output that overwhelm context windows. flutter run requires interactive terminal access for hot reload. flutter analyze produces unstructured text. This MCP server wraps the Flutter CLI into structured, agent-friendly tools with sensible output limits.

Key design decisions:

• Test results are two-phase: flutter_test returns a compact summary of failures. flutter_get_result fetches full error details for specific tests. This prevents a single test run from blowing the context window.
• All outputs are capped at 24KB to stay within typical tool response limits.
• flutter run is managed: The server holds the process, exposes hot reload/restart/logs/kill as separate tools, so the agent doesn't need terminal access.
• Inputs are sanitized: All commands use array-based process spawning (no shell). Project paths are normalized and validated. Package names and device IDs are checked for flag injection.

Tools at a glance

Tool	Parameters	Description
flutter_test	project_dir, [test_path], [test_name], [extra_args]	Run tests and return a compact summary of failures only. Use flutter_get_result to drill into specific failures.
flutter_get_result	test_run_id, test_ids	Get full error details for specific test IDs from a previous flutter_test run. Output capped at 24KB.
flutter_run	project_dir, [device], [is_debug], [dont_detach], [extra_args]	Start a Flutter app on device (e.g. macos, chrome, emulator ID) in debug or release mode. By default detaches after the app starts and returns a run_id.
flutter_hot_reload	run_id	Hot reload a running app.
flutter_hot_restart	run_id	Hot restart a running app.
flutter_kill	run_id	Kill a running app. Graceful shutdown, force-kills after 5s.
flutter_logs	run_id	Get logs from a running app. Returns the most recent output, capped at 24KB.
flutter_analyze	project_dir	Run static analysis. Returns structured issues with severity, file, line, column, and rule name.
flutter_devices	[wireless]	List available devices (simulators, emulators, physical). Skips wireless scan by default.
flutter_clean	project_dir	Delete build artifacts. Useful when builds get into a bad state.
flutter_pub_get	project_dir	Resolve and download dependencies.
flutter_pub_add	project_dir, packages, [dev]	Add one or more packages. Supports dev dependencies.
flutter_gen_l10n	project_dir	Generate localization files from ARB files.
flutter_build	project_dir, target, [debug], [extra_args]	Build the app for a target platform (apk, ios, web, macos, etc.).
flutter_build_runner	project_dir, [delete_conflicting]	Run build_runner for code generation (freezed, json_serializable, drift, etc.).

Parameters in [brackets] are optional.

Install

Requires Node.js 18+ and Flutter SDK on your PATH.

npm install -g flutter-dev-mcp

Or run directly with npx (recommended):

npx -y flutter-dev-mcp

Options

--limit-tools  Only expose tools that provide significant benefit over
               direct CLI usage (testing, app lifecycle, logs). Omits
               analyze, devices, clean, pub get/add, gen-l10n, build,
               and build_runner, which agents can run via shell.

Configuration

Claude Code (CLI)

Easy: claude mcp add flutter-dev -- npx -y flutter-dev-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Codex / Other agents

Any agent that supports MCP can use this server. Point it at the stdio transport:

npx -y flutter-dev-mcp

The server communicates over stdin/stdout using the MCP JSON-RPC protocol.

Tools

Testing

flutter_test

Run tests and get a summary of failures.

Parameter	Type	Required	Description
project_dir	string	yes	Path to the Flutter project
test_path	string	no	Specific test file or directory
test_name	string	no	Filter by test name (plain string match)
extra_args	string[]	no	Additional flags (e.g. ["--coverage", "--dart-define=KEY=VALUE"])

Returns a test_run_id and an array of failed tests with short error excerpts. Pass the test_run_id to flutter_get_result for full details.

flutter_get_result

Get full error output for specific test IDs from a previous run.

Parameter	Type	Required	Description
test_run_id	number	yes	From a previous flutter_test call
test_ids	number[]	yes	Test IDs to get details for

Output is capped at 24KB total. If a single test exceeds that, its error is truncated. If multiple tests would exceed it, only tests that fit are returned.

App lifecycle

flutter_run

Start a Flutter app and get a run_id for subsequent commands.

Parameter	Type	Required	Default	Description
project_dir	string	yes		Path to the Flutter project
device	string	no	""	Device ID (e.g. chrome, macos, emulator ID)
is_debug	boolean	no	true	Debug mode (true) or release mode (false)
dont_detach	boolean	no	false	Wait for app to exit instead of returning after start
extra_args	string[]	no	[]	Additional flags (e.g. ["--flavor=dev", "--dart-define=KEY=VALUE"])

flutter_hot_reload

Trigger a hot reload on a running app.

Parameter	Type	Required	Description
run_id	number	yes	From a previous flutter_run call

flutter_hot_restart

Trigger a hot restart on a running app.

Parameter	Type	Required	Description
run_id	number	yes	From a previous flutter_run call

flutter_kill

Kill a running app. Sends q for graceful shutdown, force-kills after 5s.

Parameter	Type	Required	Description
run_id	number	yes	From a previous flutter_run call

flutter_logs

Get logs from a running app. Returns the most recent output, capped at 24KB.

Parameter	Type	Required	Description
run_id	number	yes	From a previous flutter_run call

Analysis

flutter_analyze

Run static analysis. Returns structured issues with severity, file location, and lint rule name.

Parameter	Type	Required	Description
project_dir	string	yes	Path to the Flutter project

flutter_devices

List available devices.

Parameter	Type	Required	Default	Description
wireless	boolean	no	false	Include wireless devices (slower)

Build

flutter_build

Build the app for a target platform. Can take a long time for release builds.

Parameter	Type	Required	Default	Description
project_dir	string	yes		Path to the Flutter project
target	string	yes		Build target: apk, appbundle, ios, ipa, web, macos, windows, linux, aar, bundle, ios-framework, macos-framework
debug	boolean	no	true	Debug mode (true) or release mode (false)
extra_args	string[]	no	[]	Additional flags (e.g. ["--simulator", "--flavor=dev"])

Dependencies & codegen

flutter_pub_get

Resolve and download dependencies.

Parameter	Type	Required	Description
project_dir	string	yes	Path to the Flutter project

flutter_pub_add

Add packages to the project.

Parameter	Type	Required	Default	Description
project_dir	string	yes		Path to the Flutter project
packages	string[]	yes		Package names (e.g. ["http", "provider"])
dev	boolean	no	false	Add as dev dependency

flutter_clean

Delete build artifacts. Useful when builds get into a bad state.

Parameter	Type	Required	Description
project_dir	string	yes	Path to the Flutter project

flutter_gen_l10n

Generate localization files from ARB files.

Parameter	Type	Required	Description
project_dir	string	yes	Path to the Flutter project

flutter_build_runner

Run dart run build_runner build for code generation (freezed, json_serializable, drift, etc.).

Parameter	Type	Required	Default	Description
project_dir	string	yes		Path to the Flutter project
delete_conflicting	boolean	no	true	Delete conflicting outputs before building

Building from source

git clone <repo-url>
cd flutter-dev-mcp
npm install
npm run build
node dist/index.js

License

MIT