flutter-mcp-toolkit

Inspect and drive a running Flutter app from your AI assistant.

• 📖 Docs: docs.page/arenukvern/mcp_flutter
• 🤝 Contribute: guide · contributors · code of conduct · security

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, all over the universal AutomationDriver contract. See The Automation Chain. (OpenAI describes this pattern as harness engineering.)

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.

Get started in 4 steps

# 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 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 package, and oka as the build+lifecycle runner. New: The Automation Chain guide + flutter-mcp-automation-chain skill.

• 2026-07-11 - v4 new Live Demos records: v4 semantic snapshot etc.. with Grok Build CLI, v4 with IntentCall power - WebMCP projection

• 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

Docker / MCP Registry install

The official registry serves an OCI image from GHCR. Point any MCP client at it:

{
  "mcpServers": {
    "flutter-mcp-toolkit": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "ghcr.io/arenukvern/flutter-mcp-toolkit:6.0.0"
      ]
    }
  }
}

See Docker guide for flags, version pinning, and networking notes.

Maintainers submitting to official stores: marketplace submission runbook. Full matrix: marketplace distribution.

Documentation

• Docs for AI Agent and Human - wiki + llms.txt
• Migrating v2 → v3 — fmt_* MCP tools, binaries, client config keys, validate-runtime.
• Migrating to projections & composition — WebMCP auto-registration removal, bootstrapFlutter parameter removal, intentcall renames.
• MCPCallEntry to AgentCallEntry migration — MCPCallEntry removal, AgentCallEntry, platform codegen sync, fmt_migrate_agent_entries.
• IntentCall consumer guide — hosted intentcall_* dependency policy, consumer proof gates, and the boundary between mcp_flutter and upstream IntentCall architecture.
• Why this repo matters — what it is, why it exists.
• CLI vs MCP — pick the right mode.
• The Automation Chain — why the chain exists; MCP/CLI/harness/oka tier picker and first loops.
• Feature map — the 31 tools.
• AI agent setup - for AI Agents.
• Marketplace distribution — Claude, Cursor, Codex, skills.sh.
• Architecture — for contributors.
• Quick Start, Configuration, MCP RPC description

Published packages

Package	Pub.dev	Role
mcp_toolkit		Flutter app package for runtime MCP tools/resources and toolkit bootstrap.
flutter_mcp_toolkit_core		Pure-Dart shared command/result/capability types.
flutter_mcp_toolkit_capability_kernel		Capability kernel contracts for composable MCP units.
flutter_mcp_toolkit_capability_core		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 contract (universal_automation_* family):

Guide: The Automation Chain · skill: flutter-mcp-automation-chain.

The showcase/ folder holds examples that test the whole stack end-to-end — a minimal instrumented Flutter app (showcase/flutter_demo) and a static web page (showcase/web_demo) — each driven live by a checked-in composition root:

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), so one observe/act/verify vocabulary covers Flutter apps, browsers, and OS-native targets — the same pipeline composition style oka uses.

Development support

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.

Dynamic Tools Registration

Flutter apps can register custom tools and resources at runtime. See how it works in this short YouTube video. 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 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. See Quick Start for more details. See original motivation 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 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, how it can be modified to improve security if needed.

This MCP server is verified by MseeP.ai.

🔧 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 (maintainer releases, binary checksums) and the contribution guide. Pull requests and issues: GitHub.

✨ Contributors

Huge thanks to all contributors for making this project better!

This roster is maintained with all-contributors. To add someone, update .all-contributorsrc and regenerate the README table, or use the all-contributors bot/CLI from a PR. More detail: docs/contributing/contributors.mdx.

📖 Learn More

• Flutter DevTools Documentation
• Dart VM Service Protocol
• Flutter DevTools RPC Constants (I guess and hope they are correct:))

Star History

📄 License

MIT - Feel free to use in your projects!

Flutter and Dart are trademarks of Google LLC.