# flutter-mcp-toolkit [![MCP Toplist](https://mcptoplist.com/badge/glama%2FArenukvern%2Fmcp_flutter.svg)](https://mcptoplist.com/server/glama%2FArenukvern%2Fmcp_flutter) _Inspect and drive a running Flutter app from your AI assistant._ [![skills.sh](https://skills.sh/b/arenukvern/mcp_flutter)](https://skills.sh/arenukvern/mcp_flutter) [![pub: mcp_toolkit](https://img.shields.io/pub/v/mcp_toolkit.svg?include_prereleases)](https://pub.dev/packages/mcp_toolkit) [![Contract Gates](https://github.com/Arenukvern/mcp_flutter/actions/workflows/contract_gates.yml/badge.svg?branch=main)](https://github.com/Arenukvern/mcp_flutter/actions/workflows/contract_gates.yml) [![intentcall eval gates](https://github.com/Arenukvern/mcp_flutter/actions/workflows/intentcall_eval.yml/badge.svg?branch=main)](https://github.com/Arenukvern/mcp_flutter/actions/workflows/intentcall_eval.yml) [![skill-assets-drift](https://github.com/Arenukvern/mcp_flutter/actions/workflows/skill_assets_drift.yml/badge.svg?branch=main)](https://github.com/Arenukvern/mcp_flutter/actions/workflows/skill_assets_drift.yml) [![Docs](https://img.shields.io/badge/docs-docs.page-blue)](https://docs.page/arenukvern/mcp_flutter/) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Arenukvern/mcp_flutter) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Flutter](https://img.shields.io/badge/Flutter-%3E%3D3.44-blue.svg)](https://flutter.dev) [![smithery badge](https://smithery.ai/badge/@Arenukvern/mcp_flutter)](https://smithery.ai/server/@Arenukvern/mcp_flutter) [![Official MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.Arenukvern%2Fflutter--mcp--toolkit-blue?logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/v0/servers/io.github.Arenukvern%2Fflutter-mcp-toolkit/versions) [![All Contributors](https://img.shields.io/github/all-contributors/Arenukvern/mcp_flutter?color=ee8449&style=flat-square)](https://github.com/Arenukvern/mcp_flutter#contributors-) [![maintained with Skill Steward](https://raw.githubusercontent.com/Arenukvern/skill_steward/main/docs/brand/assets/svg/badge-light.svg)](https://github.com/Arenukvern/skill_steward)
- ๐Ÿ“– **Docs:** [docs.page/arenukvern/mcp_flutter](https://docs.page/arenukvern/mcp_flutter/) - ๐Ÿค **Contribute:** [guide](docs/contributing/contribution_guide.mdx) ยท [contributors](docs/contributing/contributors.mdx) ยท [code of conduct](CODE_OF_CONDUCT.md) ยท [security](SECURITY.md) `flutter-mcp-toolkit` is a Dart MCP server + Flutter package for AI agents (Codex, Zed, Cursor, Intent, Claude Code, Cline, and more). Agents can inspect a running Flutter app, take semantic snapshots, tap widgets, type into forms, hot-reload, and read logs. Apps can also register their own MCP tools and resources at runtime via MCP Toolkit โ€” all without leaving the conversation. The result is a closed feedback loop between agent and app. And one step further: the toolkit is becoming a **chain of declarative automation APIs** โ€” the same observe/act/verify vocabulary runs through interactive MCP (`fmt_*`), the CLI, programmatic Dart scenarios (`flutter_mcp_harness`), and declarative build+lifecycle runners like [oka](https://github.com/Arenukvern/oka), all over the universal `AutomationDriver` contract. See [The Automation Chain](docs/start_here/automation_chain.mdx). (OpenAI describes this pattern as [harness engineering](https://openai.com/index/harness-engineering/).) ![Watercolor comic infographic explaining flutter-mcp-toolkit: install fmtk, add it to a Flutter app, connect an AI agent, then inspect, tap, reload, and prove changes in a close feedback loop.](docs/assets/flutter-mcp-toolkit-infographic.png) The picture's story: the toolkit gives an AI assistant a shared window and control loop into a running Flutter app, so it can inspect state, act like a user, hot reload, read proof, and use custom tools from your app instead of guessing. ![View Screenshots](docs/view_screenshots.gif) ## Get started in 4 steps ```bash # 1. Install the binary curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash # Installs flutter-mcp-toolkit plus the short fmtk alias for repeated CLI loops. # 2. Add the toolkit to your Flutter app cd my-flutter-app flutter-mcp-toolkit codegen-init # adds mcp_toolkit + emits main.dart snippet # 3. Install skills for your AI agent flutter-mcp-toolkit init claude-code # or: cursor | codex | cline | agents-skills | all # Alternative (skills only): npx skills add Arenukvern/mcp_flutter -a cursor -y # 4. Run flutter run --debug ``` That's it. Your AI agent can now inspect and drive the running app โ€” and your app can expose **custom MCP tools at runtime** (see [Dynamic Tools Registration](#dynamic-tools-registration) below). ## ๐Ÿ“ฐ News - **2026-10-02** โ€” 6.0.0 released: the **invoke tier** (ADR-0017) โ€” the app's intent registry is the single action source; the harness driver lists (`driver.actions()`) and invokes it (`InvokeAction`) with schema-validated args, `IntentAutomationAction.custom` routes hints, and any web surface (Jaspr, plain JS) composes via `window.__mcpActions`. `flutter_mcp_harness` 0.2.x on pub.dev; server 6.0.0 on the MCP registry. - **2026-10-01** โ€” The toolkit is becoming a chain of declarative automation APIs: universal `AutomationDriver` contracts (`universal_automation_*`), the programmatic [`flutter_mcp_harness`](https://pub.dev/packages/flutter_mcp_harness) package, and [oka](https://github.com/Arenukvern/oka) as the build+lifecycle runner. New: [The Automation Chain](docs/start_here/automation_chain.mdx) guide + `flutter-mcp-automation-chain` skill. - **2026-07-11** - v4 new Live Demos records: [v4 semantic snapshot etc.. with Grok Build CLI](https://youtu.be/P0ObCyt0k3M), [v4 with IntentCall power - WebMCP projection](https://www.youtube.com/watch?v=mX4xxVeImq0) - **2026-05-26** โ€” v3.1.0: Platform-view capture routing, macOS/iOS Simulator host screenshots, web CDP tab capture (SCK โ†’ CDP โ†’ flutter_layer), and cross-platform showcase platform views. ## Install from marketplaces | Platform | Command / link | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Any agent (recommended)** | `flutter-mcp-toolkit init ` โ€” see [AI agent setup](docs/ai_agents/overview.mdx) | | **Claude Code (git catalog)** | `/plugin marketplace add Arenukvern/mcp_flutter` then install `flutter-mcp-toolkit` | | **Codex (git catalog)** | `codex plugin marketplace add Arenukvern/mcp_flutter` | | **Cursor (local plugin)** | `flutter-mcp-toolkit init cursor` | | **Skills only** | `npx skills add Arenukvern/mcp_flutter -a -y` (add MCP via `init` or manual JSON) | | **MCP registries** | [Official MCP Registry](https://registry.modelcontextprotocol.io) โ€” server `io.github.Arenukvern/flutter-mcp-toolkit` (OCI image: `ghcr.io/arenukvern/flutter-mcp-toolkit`), [Smithery](https://smithery.ai/server/@Arenukvern/mcp_flutter), [MseeP](https://mseep.ai/app/03aa0f2d-4ef7-40ae-93de-c7b87e0ac32d) | ### Docker / MCP Registry install The official registry serves an OCI image from GHCR. Point any MCP client at it: ```json { "mcpServers": { "flutter-mcp-toolkit": { "command": "docker", "args": [ "run", "-i", "--rm", "--network=host", "ghcr.io/arenukvern/flutter-mcp-toolkit:6.0.0" ] } } } ``` See [Docker guide](mcp_server_dart/DOCKER.md) for flags, version pinning, and networking notes. Maintainers submitting to official stores: [marketplace submission runbook](docs/contributing/marketplace_submission_runbook.mdx). Full matrix: [marketplace distribution](docs/ai_agents/marketplace_distribution.mdx). ## Documentation - **[Docs for AI Agent and Human](https://docs.page/arenukvern/mcp_flutter)** - wiki + llms.txt - **[Migrating v2 โ†’ v3](docs/start_here/migration_v2_to_v3.mdx)** โ€” `fmt_*` MCP tools, binaries, client config keys, `validate-runtime`. - **[Migrating to projections & composition](docs/start_here/migration_toolkit_projections.mdx)** โ€” WebMCP auto-registration removal, `bootstrapFlutter` parameter removal, intentcall renames. - **[MCPCallEntry to AgentCallEntry migration](docs/start_here/migration_mcp_call_entry_to_agent_call_entry.md)** โ€” `MCPCallEntry` removal, `AgentCallEntry`, platform `codegen sync`, `fmt_migrate_agent_entries`. - **[IntentCall consumer guide](docs/intentcall/README.md)** โ€” hosted `intentcall_*` dependency policy, consumer proof gates, and the boundary between `mcp_flutter` and upstream IntentCall architecture. - **[Why this repo matters](docs/start_here/why_this_repo_matters.mdx)** โ€” what it is, why it exists. - **[CLI vs MCP](docs/start_here/cli_vs_mcp.mdx)** โ€” pick the right mode. - **[The Automation Chain](docs/start_here/automation_chain.mdx)** โ€” why the chain exists; MCP/CLI/harness/oka tier picker and first loops. - **[Feature map](docs/start_here/feature_map.mdx)** โ€” the 31 tools. - **[AI agent setup](docs/ai_agents/overview.mdx)** - for AI Agents. - **[Marketplace distribution](docs/ai_agents/marketplace_distribution.mdx)** โ€” Claude, Cursor, Codex, skills.sh. - **[Architecture](ARCHITECTURE.md)** โ€” for contributors. - **[Quick Start](QUICK_START.md)**, **[Configuration](CONFIGURATION.md)**, **[MCP RPC description](MCP_RPC_DESCRIPTION.md)** ## Published packages | Package | Pub.dev | Role | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `mcp_toolkit` | [![pub package](https://img.shields.io/pub/v/mcp_toolkit.svg?include_prereleases)](https://pub.dev/packages/mcp_toolkit) [![pub points](https://img.shields.io/pub/points/mcp_toolkit.svg)](https://pub.dev/packages/mcp_toolkit/score) | Flutter app package for runtime MCP tools/resources and toolkit bootstrap. | | `flutter_mcp_toolkit_core` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_core.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_core) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_core.svg)](https://pub.dev/packages/flutter_mcp_toolkit_core/score) | Pure-Dart shared command/result/capability types. | | `flutter_mcp_toolkit_capability_kernel` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_capability_kernel.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_capability_kernel) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_capability_kernel.svg)](https://pub.dev/packages/flutter_mcp_toolkit_capability_kernel/score) | Capability kernel contracts for composable MCP units. | | `flutter_mcp_toolkit_capability_core` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_capability_core.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_capability_core) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_capability_core.svg)](https://pub.dev/packages/flutter_mcp_toolkit_capability_core/score) | Server-side `fmt_*` capability implementation. | The server binary lives in `mcp_server_dart` and is shipped through GitHub Release artifacts as `flutter-mcp-toolkit`, `fmtk`, and `flutter-mcp-toolkit-server`; it is not a pub.dev package. ## The automation chain Different surfaces own different parts of the lifecycle, and all of them drive the same `ext.mcp.toolkit.*` extensions through the universal [`AutomationDriver`](https://github.com/xsoulspace/dart_flutter_packages) contract (`universal_automation_*` family): | Tier | Surface | Best for | | --- | --- | --- | | Interactive MCP | `fmt_*` tools | chat-driven debugging and verification | | CLI | `flutter-mcp-toolkit` / `fmtk` | one-shot commands in scripts and CI | | Programmatic Dart | [`packages/harness`](packages/harness/README.md) โ€” `flutter_mcp_harness` on pub.dev | repeatable scenarios as checked-in code | | Build + lifecycle | [oka](https://github.com/Arenukvern/oka) | declarative device builds, owned dev sessions | Guide: [The Automation Chain](docs/start_here/automation_chain.mdx) ยท skill: `flutter-mcp-automation-chain`. The [`showcase/`](showcase/) folder holds examples that test the whole stack end-to-end โ€” a minimal instrumented Flutter app ([`showcase/flutter_demo`](showcase/flutter_demo/)) and a static web page ([`showcase/web_demo`](showcase/web_demo/)) โ€” each driven live by a checked-in composition root: ```sh make drive-flutter # instrumented tier: ToolkitDriver over the VM service make drive-web # browser tier: CdpDriver over CDP (headless Chrome) ``` `packages/harness` implements the shared contract for the Flutter tier ([`ToolkitDriver`](packages/harness/README.md#automation-drivers-universal_automation_-family)), so one observe/act/verify vocabulary covers Flutter apps, browsers, and OS-native targets โ€” the same pipeline composition style oka uses. ## Development support | Need | Start here | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Contribute code or docs | [CONTRIBUTING.md](CONTRIBUTING.md) ยท [Contribution guide](docs/contributing/contribution_guide.mdx) | | Add or credit contributors | [Contributors guide](docs/contributing/contributors.mdx) ยท [`.all-contributorsrc`](.all-contributorsrc) | | Report vulnerabilities | [SECURITY.md](SECURITY.md) | | Validate local changes | `steward probe --json --profile quick` ยท `make check-contracts` | | Maintain releases | [Release train notes](CONTRIBUTING.md#maintainers) ยท [`flutter-mcp-toolkit-repo-maintainer`](plugin/skills/flutter-mcp-toolkit-repo-maintainer/SKILL.md) | | Install or update agent skills | [AI agent setup](docs/ai_agents/overview.mdx) ยท [Marketplace distribution](docs/ai_agents/marketplace_distribution.mdx) | ## What it does The default toolkit surface exposes 31 MCP tools under the `fmt_*` capability prefix across four categories (35 with the `--dumps` debug tools enabled): - **Inspection** โ€” semantic snapshot, view details, errors, screenshots, VM info - **Interaction** โ€” tap, scroll, type, fill forms, hot-reload, navigate, wait_for - **Debug** โ€” recent logs, evaluate Dart expressions - **Lifecycle** โ€” discover apps, hot-reload, hot-restart See the `flutter-mcp-toolkit-{guide,inspect,control,debug}` skills for the full reference (installed by `flutter-mcp-toolkit init` or `npx skills add Arenukvern/mcp_flutter`). Install options: [AI agent setup](docs/ai_agents/overview.mdx). ### Dynamic Tools Registration Flutter apps can register custom tools and resources at runtime. See how it works in this [short YouTube video](https://www.youtube.com/watch?v=Qog3x2VcO98). The same `arguments.connection` targeting is supported by the CLI's `exec`, `batch`, daemon `command/execute`, daemon `watch/start`, and snapshot step args. > [!NOTE] > There is official [MCP Server for Flutter from Flutter team](https://github.com/dart-lang/ai/tree/main/pkgs/dart_mcp_server) which exposes Dart tooling. > The **main goal of this project** is to bring power of MCP server tools by creating them in Flutter app, using **dynamic MCP tools registration** and close feedback loop for AI Agent. See how it works in [short YouTube video](https://www.youtube.com/watch?v=Qog3x2VcO98). See [Quick Start](https://docs.page/arenukvern/mcp_flutter) for more details. See [original motivation](https://github.com/Arenukvern/mcp_flutter/blob/main/CHANGELOG.md#210) behind the idea. ## โš ๏ธ Note on Dump RPCs Dump RPC methods (like `dump_render_tree`) can produce huge token output and are disabled by default. Enable with `--dumps`. See [mcp_server_dart README](mcp_server_dart/README.md) for the full flag surface. ## ๐Ÿ”’ Security Generally, since you use MCP server to connect to Flutter app in Debug Mode, it should be safe to use. However, I still recommend to review how it works in [ARCHITECTURE.md](ARCHITECTURE.md), how it can be modified to improve security if needed. This MCP server is verified by [MseeP.ai](https://mseep.ai). [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/arenukvern-mcp-flutter-badge.png)](https://mseep.ai/app/arenukvern-mcp-flutter) ## ๐Ÿ”ง Troubleshooting 1. **Connection Issues** - Ensure your Flutter app is running in debug mode - Verify the port matches in both Flutter app and MCP server - Check if the port is not being used by another process - Safest explicit targeting: use `arguments.connection.uri` and paste exact Flutter machine `app.debugPort.wsUri` - If response includes `connection_selection_required`, retry with `arguments.connection.targetId` using one URI from `availableTargets` (or set `arguments.connection.uri` directly) 2. **AI Tool Not Detecting Inspector** - Restart the AI tool after configuration changes - Verify the configuration JSON syntax - Check the tool's logs for connection errors 3. **Dynamic Tools Not Appearing** - Ensure `mcp_toolkit` package is properly initialized in your Flutter app - Check that tools are registered using `MCPToolkitBinding.instance.addEntries()` - Use `fmt_list_client_tools_and_resources` to verify registration - Hot reload your Flutter app after adding new tools The Flutter MCP Server is registered with Smithery's registry, making it discoverable and usable by other AI tools through a standardized interface. ### Integration Architecture ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ Flutter App with โ”‚ โ”‚ โ”‚ โ”‚ Flutter App โ”‚<--->โ”‚ mcp_toolkit โ”‚<--->โ”‚ flutter-mcp- โ”‚ โ”‚ (Debug Mode) โ”‚ โ”‚ (VM Svc. Extensions โ”‚ โ”‚ toolkit-server โ”‚ โ”‚ โ”‚ โ”‚ + Dynamic Tools) โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` ## ๐Ÿค Contributing Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) (maintainer releases, binary checksums) and the [contribution guide](docs/contributing/contribution_guide.mdx). Pull requests and issues: [GitHub](https://github.com/Arenukvern/mcp_flutter). ## โœจ Contributors Huge thanks to all contributors for making this project better! This roster is maintained with [all-contributors](https://allcontributors.org/). To add someone, update [`.all-contributorsrc`](.all-contributorsrc) and regenerate the README table, or use the all-contributors bot/CLI from a PR. More detail: [docs/contributing/contributors.mdx](docs/contributing/contributors.mdx).
Henry Mao
Henry Mao
๐Ÿš‡		 Marwen
Marwen
๐Ÿ“–		 Lawrence Sinclair
Lawrence Sinclair
๐Ÿ“– ๐Ÿ›ก๏ธ		 Frank Fiegel
Frank Fiegel
๐Ÿš‡		 Harish Anbalagan
Harish Anbalagan
๐Ÿ““ ๐Ÿ›		 Torben Keller
Torben Keller
๐Ÿ““ ๐Ÿ›		 Isfun
Isfun
๐Ÿ““ ๐Ÿ› ๐Ÿ”ฌ ๐Ÿ’ป
Cosy Studio
Cosy Studio
๐Ÿ““ ๐Ÿ› ๐Ÿ”ฌ		 Luke Memet
Luke Memet
๐Ÿ““ ๐Ÿ”ฌ ๐Ÿšง โœ…		 Commentatk Media
Commentatk Media
๐Ÿ’ป ๐Ÿšง ๐Ÿ“–		 Umit Arslan
Umit Arslan
๐Ÿ’ป ๐Ÿšง		 Joel Kitching
Joel Kitching
๐Ÿ’ป ๐Ÿšง		 Jean-Luc Thumm
Jean-Luc Thumm
๐Ÿšง		 Miguel Casagrande
Miguel Casagrande
๐Ÿ’ป ๐Ÿšง
drown0315
drown0315
๐Ÿ’ป ๐Ÿšง ๐Ÿ›		 druyang
druyang
๐Ÿ’ป ๐Ÿšง ๐Ÿ›		 dipsy
dipsy
๐Ÿ’ป ๐Ÿšง ๐Ÿ›		 wenyue
wenyue
๐Ÿ’ป ๐Ÿšง		 Christophe
Christophe
๐Ÿ“– ๐Ÿ“ฆ
## ๐Ÿ“– Learn More - [Flutter DevTools Documentation](https://docs.flutter.dev/development/tools/devtools/overview) - [Dart VM Service Protocol](https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md) - [Flutter DevTools RPC Constants (I guess and hope they are correct:))](https://github.com/flutter/devtools/tree/87f8016e2610c98c3e2eae8b1c823de068701dfd/packages/devtools_app/lib/src/shared/analytics/constants) ## Star History Star History Chart ## ๐Ÿ“„ License [MIT](LICENSE) - Feel free to use in your projects! --- _Flutter and Dart are trademarks of Google LLC._