FlutterHelm
FlutterHelm is an agent-safe orchestration layer / MCP server for Flutter development.
English docs: Overview | User Guide | Troubleshooting
Japanese docs: 概要 | ユーザーガイド | トラブルシューティング
It composes the official Dart and Flutter MCP server, the flutter CLI, vm_service, profiling flows, native handoff, and optional runtime interaction drivers behind a consistent session/resource/safety contract.
FlutterHelm does not try to replace those tools.
It adds session management, safety controls, artifact/resource handling, compatibility checks, and workflow-level orchestration on top of official interfaces.
Public Repository Notes
- Repository:
CAPHTECH/flutterhelm
- License: MIT
- Public contract version:
0.2.0-stable
- Stable transport:
stdio
- Repo-local Codex / Claude plugin: plugins/flutterhelm
- Support levels:
stable: core FlutterHelm workflowsbeta: runtime_interaction, custom stdio_json providers, native_buildpreview: HTTP transport
Start Here
What You Can Do With FlutterHelm
- discover and select Flutter workspaces
- run, attach, and stop Flutter apps
- inspect logs, runtime errors, widget trees, app state, and screenshots
- run unit, widget, and integration tests with report and coverage resources
- capture CPU, timeline, and memory profiling artifacts
- generate iOS and Android native handoff bundles
- pin, retain, and inspect artifacts
- check compatibility, adapter health, and observability status
- use the official Flutter MCP delegate path first, with automatic fallback when needed
Opt-in beta workflows add:
- runtime interaction:
tap_widget, enter_text, scroll_until_visible, hot_reload, hot_restart
- custom
stdio_json adapters
- native build orchestration:
native_project_inspect, native_build_launch, native_attach_flutter_runtime, native_stop
Why a Separate Layer Exists
The official Dart and Flutter MCP server is already powerful, but Flutter development still spans multiple layers:
- the official MCP server is still evolving
- the
flutter CLI remains the standard execution path
- profiling and low-level runtime inspection still depend on DevTools / DTD /
vm_service
- native debugging still belongs to Xcode / Android Studio
- large outputs work better as Resources than as inline tool results
FlutterHelm exists to make those layers usable through a stable, agent-friendly contract.
Core Design Principles
-
Compose, do not replace
Respect the official Flutter MCP server, flutter CLI, DevTools, and native debuggers.
-
Session-first
Treat run, attach, profile, and test as reusable session state instead of one-shot commands.
-
Resource-first
Publish heavy outputs like widget trees, runtime errors, timelines, memory snapshots, and test reports as Resources.
-
Safe-by-default
Default to read-only access and gate risky mutation through approvals or ownership policy.
-
Workflow-grouped
Expose capabilities in workflow groups so the default surface stays small and predictable.
External Requirements
Always required:
- Dart SDK
- Flutter SDK /
flutter CLI
- an MCP client that supports Tools and Resources
iOS workflows additionally require:
Beta runtime_interaction additionally requires:
- Node.js /
npx
@mobilenext/mobile-mcp
Beta native_build additionally requires:
- a
nativeBuild stdio_json provider, such as an XcodeBuildMCP-like backend
Recommended Initial Workflows
enabledWorkflows:
- workspace
- session
- launcher
- runtime_readonly
- tests
profiling and platform_bridge are enabled by default in the current implementation.
runtime_interaction is implemented but remains opt-in.
Minimal MCP Setup
{
"mcpServers": {
"flutterhelm": {
"command": "npx",
"args": ["--yes", "--quiet", "github:CAPHTECH/flutterhelm", "serve"]
}
}
}
