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