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

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.

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.

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.

flutter_hot_reload

Trigger a hot reload on a running app.

flutter_hot_restart

Trigger a hot restart on a running app.

flutter_kill

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

flutter_logs

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

Analysis

flutter_analyze

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

flutter_devices

List available devices.

Build

flutter_build

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

Dependencies & codegen

flutter_pub_get

Resolve and download dependencies.

flutter_pub_add

Add packages to the project.

flutter_clean

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

flutter_gen_l10n

Generate localization files from ARB files.

flutter_build_runner

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

Building from source

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

License

MIT