MCP Server + Flutter MCP Toolkit

• 📖 文档： docs.page/arenukvern/mcp_flutter
• 🤝 参与贡献： 指南 · 贡献者 · 行为准则 · 安全

flutter-mcp-toolkit 是一个面向 AI Agent（Codex、Zed、Cursor、Intent、Claude Code、Cline 等）的 Dart MCP 服务和 Flutter 软件包。Agent 可以检查正在运行的 Flutter 应用、获取语义快照、点击组件、在表单中输入内容、热重载以及读取日志。应用还可以通过 MCP Toolkit 在运行时注册自己的 MCP 工具和资源，整个过程无需离开对话。由此，Agent 与应用之间形成了一个闭环反馈。

更进一步：该工具包正发展为一套声明式自动化 API 链——同一套观察／操作／验证词汇贯穿交互式 MCP（fmt_*）、命令行、程序化 Dart 场景（flutter_mcp_harness），以及 oka 等声明式构建与生命周期运行器，并统一基于通用的 AutomationDriver 契约。请参阅自动化链。（OpenAI 将这一模式称为构建环境工程。）

这张图片讲述的故事：该工具包为 AI 助手提供了一个共享窗口和控制循环，使其能够连接到正在运行的 Flutter 应用，从而检查状态、像用户一样操作、热重载、读取验证结果，并使用应用中的自定义工具，而不是靠猜测。

4 步快速入门

# 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

就是这么简单。现在，你的 AI Agent 可以检查并操控正在运行的应用，而你的应用也可以在运行时公开自定义 MCP 工具（请参阅下文的动态工具注册）。

📰 新闻

• 2026-10-02 — 发布 6.0.0：调用层（ADR-0017）——应用的意图注册表是唯一的操作来源；harness driver 会列出它（driver.actions()），并通过带有经过 schema 验证的参数调用它（InvokeAction）；IntentAutomationAction.custom 会路由提示；任何 Web 界面（Jaspr、纯 JS）都可以通过 window.__mcpActions 组合。flutter_mcp_harness 0.2.x 已发布到 pub.dev；服务端 6.0.0 已发布到 MCP registry。

• 2026-10-01 — 该工具包正逐步发展为一系列声明式自动化 API：通用 AutomationDriver 契约（universal_automation_*）、程序化的 flutter_mcp_harness 包，以及作为构建和生命周期运行器的 oka。新增：自动化链指南和 flutter-mcp-automation-chain 技能。

• 2026-07-11 - v4 新增现场演示录制：使用 Grok Build CLI 演示 v4 语义快照等功能、展示 v4 的 IntentCall 能力——WebMCP 投影

• 2026-05-26 — v3.1.0：平台视图捕获路由、macOS/iOS Simulator 主机截图、Web CDP 标签页捕获（SCK → CDP → flutter_layer），以及跨平台展示平台视图。

从市场安装

平台	命令 / 链接
任意 Agent（推荐）	flutter-mcp-toolkit init <agent> — 查看 AI Agent 设置
Claude Code（Git 目录）	/plugin marketplace add Arenukvern/mcp_flutter 然后安装 flutter-mcp-toolkit
Codex（Git 目录）	codex plugin marketplace add Arenukvern/mcp_flutter
Cursor（本地插件）	flutter-mcp-toolkit init cursor
仅安装技能	npx skills add Arenukvern/mcp_flutter -a <agent> -y（通过 init 或手动配置 JSON 添加 MCP）
MCP 注册表	官方 MCP 注册表 — 服务 io.github.Arenukvern/flutter-mcp-toolkit（OCI 镜像：ghcr.io/arenukvern/flutter-mcp-toolkit）、Smithery、MseeP

Docker / MCP 注册表安装

官方注册表通过 GHCR 提供 OCI 镜像。将任意 MCP 客户端指向该镜像：

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

有关标志、版本固定和网络说明，请参阅 Docker 指南。

向官方商店提交内容的维护者请参阅：市场提交操作手册。完整列表：市场分发。

文档

• 面向 AI Agent 和人类的文档 - wiki + llms.txt
• 从 v2 迁移到 v3 — fmt_* MCP 工具、二进制文件、客户端配置键、validate-runtime。
• 迁移到投影与组合 — 移除 WebMCP 自动注册、移除 bootstrapFlutter 参数、重命名 intentcall。
• 从 MCPCallEntry 迁移到 AgentCallEntry — 移除 MCPCallEntry、AgentCallEntry、平台 codegen sync、fmt_migrate_agent_entries。
• IntentCall 使用者指南 — 托管的 intentcall_* 依赖策略、使用者验证门槛，以及 mcp_flutter 与上游 IntentCall 架构之间的边界。
• 为什么这个仓库很重要 — 它是什么，以及它为何存在。
• CLI 与 MCP — 选择合适的模式。
• 自动化链 — 说明这条链存在的原因；MCP/CLI/测试框架/oka 层级选择器和初始循环。
• 功能地图 — 31 个工具。
• AI Agent 设置 - 面向 AI Agent。
• 市场分发 — Claude、Cursor、Codex、skills.sh。
• 架构 — 面向贡献者。
• 快速入门、配置、MCP RPC 说明

已发布的软件包

软件包	Pub.dev	角色
mcp_toolkit		用于运行时 MCP 工具、资源和工具包引导的 Flutter 应用软件包。
flutter_mcp_toolkit_core		纯 Dart 共享命令／结果／能力类型。
flutter_mcp_toolkit_capability_kernel		用于可组合 MCP 单元的能力内核契约。
flutter_mcp_toolkit_capability_core		服务端 fmt_* 能力实现。

服务端二进制文件位于 mcp_server_dart，并通过 GitHub Release 工件以 flutter-mcp-toolkit、fmtk 和 flutter-mcp-toolkit-server 的名称发布；它不是 pub.dev 软件包。

自动化链路

不同的界面负责生命周期中的不同环节，但它们都会通过通用的 AutomationDriver 契约（universal_automation_* 系列）驱动相同的 ext.mcp.toolkit.* 扩展：

层级	界面	适用场景
交互式 MCP	fmt_* 工具	通过聊天进行调试和验证
CLI	flutter-mcp-toolkit / fmtk	在脚本和 CI 中执行一次性命令
Dart 编程接口	packages/harness — pub.dev 上的 flutter_mcp_harness	将可重复的场景作为代码纳入版本控制
构建 + 生命周期	oka	声明式设备构建、自主管理的开发会话

指南：自动化链路 · 技能：flutter-mcp-automation-chain。

showcase/ 文件夹中包含端到端测试整个技术栈的示例——一个经过最小化埋点的 Flutter 应用 （showcase/flutter_demo）和一个静态网页 （showcase/web_demo）——两者都由纳入版本控制的组合根实时驱动：

make drive-flutter   # instrumented tier: ToolkitDriver over the VM service
make drive-web       # browser tier: CdpDriver over CDP (headless Chrome)

packages/harness 为 Flutter 层实现了共享契约 （ToolkitDriver）， 因此，一套统一的观察／操作／验证词汇可适用于 Flutter 应用、浏览器和 操作系统原生目标——采用与 oka 相同的流水线组合风格。

开发支持

需求	从这里开始
贡献代码或文档	CONTRIBUTING.md · 贡献指南
添加或致谢贡献者	贡献者指南 · .all-contributorsrc
报告安全漏洞	SECURITY.md
验证本地更改	steward probe --json --profile quick · make check-contracts
维护发布流程	发布流程说明 · flutter-mcp-toolkit-repo-maintainer
安装或更新 Agent 技能	AI Agent 设置 · 市场分发

功能说明

默认工具包界面在四个类别下，通过 fmt_* 能力前缀提供 31 个 MCP 工具（启用 --dumps 调试工具后为 35 个）：

• 检查 — 语义快照、视图详情、错误、屏幕截图、VM 信息
• 交互 — 点击、滚动、输入、填写表单、热重载、导航、wait_for
• 调试 — 最近的日志、求值 Dart 表达式
• 生命周期 — 发现应用、热重载、热重启

完整参考请参阅 flutter-mcp-toolkit-{guide,inspect,control,debug} 技能（通过 flutter-mcp-toolkit init 或 npx skills add Arenukvern/mcp_flutter 安装）。 安装选项：AI Agent 设置。

动态工具注册

Flutter 应用可以在运行时注册自定义工具和资源。请观看这个简短的 YouTube 视频了解其工作原理。 CLI 的 exec、batch、守护进程 command/execute、守护进程 watch/start 以及快照步骤参数也支持相同的 arguments.connection 定向方式。

说明

Flutter 团队提供了官方的 Flutter MCP 服务，用于提供 Dart 工具。 本项目的主要目标是通过在 Flutter 应用中创建工具，借助动态 MCP 工具注册，为 AI Agent 带来 MCP 服务工具的强大能力，并形成紧密的反馈循环。请观看简短的 YouTube 视频了解其工作原理。更多详情请参阅快速入门。有关这一想法的最初动机，请参阅相关说明。

⚠️ 关于 Dump RPC 的说明

Dump RPC 方法（例如 dump_render_tree）可能会产生大量 Token 输出，默认处于禁用状态。使用 --dumps 启用。完整的标志说明请参阅 mcp_server_dart README。

🔒 安全

通常，由于你使用 MCP 服务连接到调试模式下的 Flutter 应用，因此应该可以安全使用。不过，我仍建议查看 ARCHITECTURE.md，了解其工作原理，以及在需要时如何修改以提升安全性。

此 MCP 服务已通过 MseeP.ai 验证。

🔧 故障排除

1. 连接问题

   • 确保 Flutter 应用正在调试模式下运行
   • 确认 Flutter 应用和 MCP 服务中的端口一致
   • 检查端口是否未被其他进程占用
   • 最安全的显式定向方式：使用 arguments.connection.uri，并粘贴 Flutter machine 的 app.debugPort.wsUri 完整值
   • 如果响应包含 connection_selection_required，请使用 availableTargets 中的一个 URI，通过 arguments.connection.targetId 重试（或直接设置 arguments.connection.uri）

2. AI 工具未检测到 Inspector

   • 更改配置后，重启 AI 工具
   • 确认配置 JSON 语法正确
   • 检查工具日志中是否存在连接错误

3. 未显示动态工具

   • 确保 Flutter 应用已正确初始化 mcp_toolkit 包
   • 检查是否使用 MCPToolkitBinding.instance.addEntries() 注册了工具
   • 使用 fmt_list_client_tools_and_resources 验证注册情况
   • 添加新工具后，对 Flutter 应用执行热重载

Flutter MCP Server 已在 Smithery 注册表中注册，可通过标准化接口被其他 AI 工具发现和使用。

集成架构

┌─────────────────┐     ┌───────────────────────┐     ┌─────────────────┐
│                 │     │  Flutter App with     │     │                 │
│  Flutter App    │<--->│  mcp_toolkit          │<--->│ flutter-mcp-    │
│  (Debug Mode)   │     │  (VM Svc. Extensions  │     │ toolkit-server  │
│                 │     │  + Dynamic Tools)     │     │                 │
└─────────────────┘     └───────────────────────┘     └─────────────────┘

🤝 参与贡献

欢迎参与贡献！请参阅 CONTRIBUTING.md（维护者发布、二进制校验和）和贡献指南。拉取请求和问题反馈：GitHub。

✨ 贡献者

衷心感谢所有贡献者，让这个项目变得更好！

此名单由 all-contributors 维护。 如需添加贡献者，请更新 .all-contributorsrc 并 重新生成 README 表格，或在拉取请求中使用 all-contributors bot/CLI。 更多详情：docs/contributing/contributors.mdx。

Henry Mao 🚇	Marwen 📖	Lawrence Sinclair 📖 🛡️	Frank Fiegel 🚇	Harish Anbalagan 📓 🐛	Torben Keller 📓 🐛	Isfun 📓 🐛 🔬 💻
Cosy Studio 📓 🐛 🔬	Luke Memet 📓 🔬 🚧 ✅	Commentatk Media 💻 🚧 📖	Umit Arslan 💻 🚧	Joel Kitching 💻 🚧	Jean-Luc Thumm 🚧	Miguel Casagrande 💻 🚧
drown0315 💻 🚧 🐛	druyang 💻 🚧 🐛	dipsy 💻 🚧 🐛	wenyue 💻 🚧	Christophe 📖 📦

📖 了解更多

• Flutter DevTools 文档
• Dart VM 服务协议
• Flutter DevTools RPC 常量（我猜并希望这些是正确的 :）

Star 历史

📄 许可证

MIT - 欢迎在你的项目中使用！

---

Flutter 和 Dart 是 Google LLC 的商标。