Flutter MCP Toolkit

MCP Toolkit Server（Dart）

从 v2.x 迁移

MCP 上的工具名称以 fmt_ 为前缀，二进制文件和 mcpServers 键已重命名 — 请参阅 从 v2.x 迁移到 v3.0。

架构

此项目现在使用共享的核心执行层：

1. flutter-mcp-toolkit 是规范的命令入口（连接、检查、执行、诊断）。fmtk 是同一 CLI 入口的简短别名。
2. flutter-mcp-toolkit-server 是精简的 MCP 协议适配器，可将 MCP 工具／资源调用映射到同一个核心执行器。
3. MCP tools/list 名称使用 fmt_ 能力前缀；CLI exec --name 使用命令目录中的名称或别名，不属于 MCP tools/call 命名空间。资源 URI 保持不变。

此软件包中提供了共享核心模块 flutter_mcp_core。

推荐流程

在 macOS 上，先按此顺序操作：

1. 将 mcp_toolkit 添加到应用，并调用 MCPToolkitBinding.instance.bootstrapFlutter(...)。
2. 以调试模式启动应用。
3. 运行 fmtk validate-runtime（或规范的完整命令 flutter-mcp-toolkit validate-runtime）。
4. 按以下顺序查询动态条目： fmt_list_client_tools_and_resources、 fmt_client_tool、 fmt_client_resource。

将 exec 视为专家模式。validate-runtime 是默认的首轮验证命令。

CLI v3 界面（不兼容性重大变更）

CLI 现在以 Agent 为先，并提供标准接口：

• exec --name <command> --args <json>
• schema [--name <command>]
• capabilities
• serve（通过 stdio 使用 JSON-RPC 2.0）
• snapshot create --name <id> [--args <json>]
• snapshot diff --from <id> --to <id>
• bundle create --from-snapshot <id> [--output <dir>]
• doctor [--json] [--target <path>] [--timeout-ms <n>]
• permissions status|request|open-settings [--kind visual_capture]

用于生成写入内容的命令的安全写入标志：

• snapshot create：--check --diff --backup --no-overwrite
• bundle create：--check --diff --backup --no-overwrite

exec 面向共享 CommandCatalog 中的命令（CLI 命令名可以不带前缀，因为它们只会出现在 --name 后；CLI 不属于 MCP 的 tools/call 命名空间）： connect、session_start、session_exec、session_end、diagnose、watch、explain_errors、status、discover_debug_apps、get_vm、get_extension_rpcs、hot_reload_flutter、hot_restart_flutter、get_active_ports、get_app_errors、get_screenshots、focus_window、get_view_details、inspect_widget_at_point、capture_ui_snapshot、debug_dump_layer_tree、debug_dump_semantics_tree、debug_dump_render_tree、debug_dump_focus_tree、fmt_list_client_tools_and_resources、fmt_client_tool、fmt_client_resource、dynamicRegistryStats、semantic_snapshot、tap_widget、long_press、enter_text、reveal_search、scroll、swipe、drag、hot_reload_and_capture、evaluate_dart_expression、get_recent_logs。

MCP 名称。通过 MCP tools/call 调用时，公开的工具会使用 fmt_ 能力前缀（例如 fmt_tap_widget、 fmt_hot_reload_and_capture）。启用动态注册表时，会公开 动态注册表主机的三个工具：fmt_list_client_tools_and_resources、 fmt_client_tool 和 fmt_client_resource。dynamicRegistryStats 仍可通过 CLI 目录用于底层诊断，但不属于默认的 MCP 工具界面。

交互工具（目录名称：semantic_snapshot → tap_widget / enter_text / reveal_search / scroll / swipe / long_press / drag）遵循 Playwright 风格的 ref 模型：先获取快照，再将 ref: "s_N"（以及用于检测过期状态的可选 snapshotId）传入交互工具。reveal_search 是针对屏幕外语义目标的有界辅助工具：它会获取快照、匹配一个范围较窄的选择器、最多滚动 maxAttempts 次，并返回新的 ref / snapshotId 及跟踪信息。hot_reload_and_capture 将重新加载、截图、获取新快照和错误信息合并为一个操作。evaluate_dart_expression 会针对应用的根库运行临时 Dart 表达式。有关完整界面和推荐路径，请参阅 docs/start_here/cli_quick_recipes.mdx 和 docs/guides/interaction_cookbook.mdx。

打包安装包含 flutter-mcp-toolkit 和 fmtk；以下示例使用 dart run 进行源码树开发。精简本地迭代时优先使用 fmtk；在入门、安装、PATH 和 MCP 配置文档中保留 flutter-mcp-toolkit，便于通过规范名称搜索。

CLI 与 MCP 使用相同的共享命令目录和执行器。推荐的调试路径： discover_debug_apps -> capture_ui_snapshot -> inspect_widget_at_point。 CLI 中仍提供 get_active_ports 和 dynamicRegistryStats，用于底层诊断，但默认不会通过 MCP 公开。

CLI 快速使用（v3）

# introspection
dart run bin/flutter_mcp_toolkit.dart schema
dart run bin/flutter_mcp_toolkit.dart capabilities

# one-shot execution (machine envelope)
dart run bin/flutter_mcp_toolkit.dart exec --name status --args '{}'
dart run bin/flutter_mcp_toolkit.dart exec --name get_vm --args '{}'
dart run bin/flutter_mcp_toolkit.dart exec --name get_vm --args '{"connection":{"targetId":"ws://127.0.0.1:8181/<token>/ws"}}'
dart run bin/flutter_mcp_toolkit.dart exec --name discover_debug_apps --args '{}'
dart run bin/flutter_mcp_toolkit.dart exec --name capture_ui_snapshot --args '{"connection":{"targetId":"ws://127.0.0.1:8181/<token>/ws"}}'
dart run bin/flutter_mcp_toolkit.dart exec --name inspect_widget_at_point --args '{"x":120,"y":220,"connection":{"targetId":"ws://127.0.0.1:8181/<token>/ws"}}'

# session lifecycle
dart run bin/flutter_mcp_toolkit.dart exec --name session_start --args '{"mode":"uri","uri":"ws://127.0.0.1:8181/<token>/ws"}'
dart run bin/flutter_mcp_toolkit.dart exec --name session_exec --args '{"command":"get_app_errors","arguments":{"count":4}}'
dart run bin/flutter_mcp_toolkit.dart exec --name session_end --args '{}'

# reproducible artifacts
dart run bin/flutter_mcp_toolkit.dart snapshot create --name baseline --args '{"commands":[{"name":"status","args":{}}]}' --check --diff
dart run bin/flutter_mcp_toolkit.dart snapshot diff --from baseline --to after_fix
dart run bin/flutter_mcp_toolkit.dart bundle create --from-snapshot baseline --backup

# environment preflight
dart run bin/flutter_mcp_toolkit.dart doctor --json
dart run bin/flutter_mcp_toolkit.dart permissions status
dart run bin/flutter_mcp_toolkit.dart permissions request
dart run bin/flutter_mcp_toolkit.dart permissions open-settings
dart run bin/flutter_mcp_toolkit.dart exec --name get_extension_rpcs --args '{}'

# explicit capture policy/mode
dart run bin/flutter_mcp_toolkit.dart exec --name get_screenshots --args '{"mode":"desktop_window","permissionPolicy":"auto_request_once"}'
dart run bin/flutter_mcp_toolkit.dart exec --name capture_ui_snapshot --args '{"screenshotMode":"auto","permissionPolicy":"auto_request_once"}'

# one-command runtime validation (after app launch)
dart run bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/app validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --timeout-ms 10000 \
  --post-reload-delay-ms 500 \
  --after-reload

# same, using global VM URI (equivalent to --target when only one is passed)
dart run bin/flutter_mcp_toolkit.dart --vm-service-uri ws://127.0.0.1:8181/<token>/ws validate-runtime \
  --timeout-ms 10000

# optional: install bundled skill during runtime validation
dart run bin/flutter_mcp_toolkit.dart validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --install-skill

应用检查的 CLI 运行时门控：

• 从 get_extension_rpcs 中确认包含 ext.mcp.toolkit.app_errors、ext.mcp.toolkit.view_details、ext.mcp.toolkit.view_screenshots 和 ext.mcp.toolkit.inspect_widget_at_point。
• 如果缺少这些项目，在安装并初始化 mcp_toolkit，且热重启或重新运行应用之前，应用级别的截图、布局和错误检查都将受阻。
• 如果截图中本应显示地图／摄像头／Web 视图的位置出现黑色矩形，请检查 get_view_details 中的 captureHints，或截图负载中的 platformViewsDetected 或 weakSignalsDetected。请使用 mode: desktop_window（或者保留 auto；当存在强信号时，它会在 macOS 主机上自动升级），而不是 flutter_layer。
• 主机端捕获在遇到可重试的故障时，会自动执行一次聚焦并捕获的恢复循环（负载中的 desktopCaptureRetried）。你也可以调用 focus_window，然后使用 desktop_window 重试 get_screenshots。
• 如果首次使用显式 URI 连接超时，请重试一次，并使用 doctor --json --target <ws_uri> --timeout-ms 10000 验证。
• 设置 --output-dir 时，validate-runtime 会将其 JSON 信封镜像到 <output-dir>/validate-runtime.json，截图文件则写入 <output-dir>/.mcp_screenshots/。
• 当 auto 选择 desktop_window 时，validate-runtime 会优先尝试主机端 desktop_window。执行器恢复会重试一次聚焦并捕获（desktopCaptureRetried）。如果 desktop_window 仍然失败，validate-runtime 会使用 flutter_layer 重试一次（即使检测到平台视图，例如示例中的 AppKitView 也是如此）。请检查 data.summary.capturePlatformViewsDetected、captureFocusAttempted 和 captureFallbackUsed。Web 有头捕获选项：ADR 0007。

视觉捕获权限

• doctor 保持只读。现在会报告 visual_capture_backend、visual_capture_permission、visual_capture_truth_mode 和 app_permission_bridge。
• 交互式 CLI 捕获流程默认对 exec get_screenshots、exec capture_ui_snapshot 和 validate-runtime 使用 auto_request_once。原始命令 schema 仍默认使用 check_only。
• macOS 的真实捕获模式为 desktop_window（包括 Mac 主机上的 iOS Simulator 和 Chrome / web）。屏幕录制权限属于运行 flutter-mcp-toolkit 的主机进程，而不是 Flutter 应用。使用 permissions request 显示原生提示；被拒绝后使用 permissions open-settings。
• 检测到原生平台视图（AndroidView、UiKitView、AppKitView、HtmlElementView、PlatformViewLink）时，get_view_details 和 view_screenshots 会包含 captureHints。Texture 会将 weakSignalsDetected 设为 true，并显示软警告（不会自动升级）。没有平台视图的混合引擎可以在应用中使用 MCPToolkitBinding.captureHintsContributor。
• 仅包含图像的 get_screenshots MCP 响应会在 meta 中包含路由元数据；存在 captureHints / warnings 时，还会在开头添加 JSON 文本块。
• Showcase 的 Capture 部分：macOS 上的 AppKitView（make showcase）、Web 上的 HtmlElementView（flutter run -d chrome）。开始新的 macOS 运行前，请使用 make showcase-stop。
• Web（chrome / web / web-server）：desktop_window 使用 macOS ScreenCaptureKit → Chrome CDP（Page.captureScreenshot）→ flutter_layer。全局标志：--web-browser-debugging-port、--web-port。选择启用的实时测试：RUN_WEB_CDP_INTEGRATION=1 dart test test/web_cdp_integration_test.dart。请参阅 ADR 0007。
• 对于 iOS/Android/Linux 等由应用拥有的捕获目标，必须先选定一个可访问的 VM 目标，permissions 或 doctor 才能验证由桥接支持的权限工具/资源。探测这些 平台时，请使用 --target <ws_uri> 或全局标志 --vm-service-uri <ws_uri>。
• desktop_window 绝不会静默回退。auto 可以回退到 flutter_layer，但响应始终会报告 requestedMode、actualMode、permissionStatus 和 fallbackReason。

故障排查：

• 如果 macOS 捕获被拒绝，请先重新运行 flutter-mcp-toolkit permissions status。如果状态仍为 denied，请从 CLI 打开系统设置，并向你正在使用的终端或客户端进程授予屏幕录制权限。
• 如果 macOS 上的 doctor --json 显示 visual_capture_truth_mode=flutter_layer，说明你尚未获得原生窗口像素。
• 如果 Web 的 desktop_window 失败，请使用 flutter_layer，或传入 Chrome 的 --remote-debugging-port 所使用的 --web-browser-debugging-port。对于 Web 目标，请在 validate-runtime 上传入 --flutter-device chrome。即使检测到平台视图，validate-runtime 在 desktop_window 失败后仍会重试 flutter_layer。
• 如果 macOS 桌面窗口模式下重新加载后捕获失败一次，通常是主机捕获竞争问题，而非应用故障。validate-runtime 会在返回红色结果前重试这些失败；desktop_window 截图失败后，也可能会改用 flutter_layer 重试。

故障矩阵：

• missing_mcp_toolkit_wiring：应用未公开所需的工具包扩展。修复应用启动代码并执行热重启。
• bad_target_uri_or_unreachable_vm_service：显式目标 URI 错误，或 VM 服务无法访问。
• permission_denied：主机捕获后端缺少权限。
• host_capture_backend_instability：桌面窗口捕获期间原生捕获后端发生故障，通常出现在重新加载前后。

迁移（v2.x -> v3.0.0）

• 错误元数据已移至 error.descriptor 下；不要解析旧版顶层字段。
• 类型化参数采用严格校验。以字符串编码的布尔值、对象、列表和整数现在会校验失败。
• 对于会生成写入操作的自动化流程，请先运行 --check --diff，再执行实际写入。
• 使用 --no-overwrite 时，请显式处理 write_blocked。
• 在依赖 VM 的执行前，将 flutter-mcp-toolkit doctor --json 作为预检步骤。

机器信封

单次命令会返回一个包含稳定字段的 JSON 信封：

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "schemaVersion": "core-envelope/v1",
    "command": "status",
    "timestamp": "2026-03-03T00:00:00.000Z",
    "durationMs": 2
  }
}

失败时，error 中会使用一个严格的信封，包含： code、message、details、descriptor（category、retryable、exitCode、httpLikeStatus）、recovery。

完整的契约表记录在 docs/ai_agents/troubleshooting.mdx 中。

守护进程协议

serve 通过 stdio 运行 JSON-RPC 2.0。关键方法：

• 请求：initialize、capabilities/get、schema/get、command/execute、watch/start、watch/stop、snapshot/create、snapshot/diff、bundle/create、session/start、session/end
• 通知：watch/event、session/changed

监视通知是 NDJSON JSON-RPC 通知，每个监视项的 seq 单调递增。

目标指定契约：

• command/execute：可选的 params.args.connection
• watch/start：可选的 params.args.connection（在监视循环开始前应用一次）
• snapshot/create：每个步骤均可选的 args.commands[i].args.connection

状态与锁定

• 状态根目录默认为 .flutter_mcp/
• 状态文件：.flutter_mcp/state.json
• 锁文件：.flutter_mcp/state.lock
• 快照：.flutter_mcp/snapshots/
• 包：.flutter_mcp/bundles/

状态操作会使用锁，并通过过期锁 TTL 恢复机制，安全地支持并发 Agent。

连接解析体验

服务启动时不会阻塞，并会将目标锁定推迟到执行依赖 VM 的调用时。

依赖 VM 的命令和资源采用以下解析策略：

1. 如果活动连接仍然健康，则复用该连接。
2. 否则，如果粘性目标存在于当前发现结果中，则复用该目标。
3. 否则，如果恰好发现一个目标，则自动连接。
4. 否则，如果存在多个目标且未提供明确目标，则返回 connection_selection_required 错误。

需要选择目标的错误会以结构化 JSON 返回，以便 Agent 立即重试：

{
  "code": "connection_selection_required",
  "message": "Multiple debug targets detected. Retry with URI connection.targetId.",
  "descriptor": {
    "category": "validation",
    "retryable": true,
    "exitCode": 64,
    "httpLikeStatus": 409
  },
  "details": {
    "reason": "multiple_targets",
    "availableTargets": [
      {
        "targetId": "ws://127.0.0.1:8181/<token>/ws",
        "host": "localhost",
        "port": 8181,
        "endpoint": "ws://127.0.0.1:8181/<token>/ws",
        "isSticky": false,
        "isCurrent": false
      }
    ],
    "suggestedAction": "retry_with_connection_target",
    "example": {
      "connection": { "targetId": "ws://127.0.0.1:8181/<token>/ws" }
    },
    "howToRetry": {
      "connection": { "targetId": "ws://127.0.0.1:8181/<token>/ws" }
    }
  },
  "recovery": {
    "summary": "Select an explicit VM target and retry the command.",
    "fix_command": "flutter-mcp-toolkit exec --name discover_debug_apps --args '{}'"
  }
}

CLI 单次调用和守护进程调用使用相同的握手语义。对于目标不明确的多目标会话，请使用明确的选择器重试：

{
  "connection": { "targetId": "ws://127.0.0.1:8181/<token>/ws" }
}

现在，所有依赖 VM 的 MCP 工具都接受可选的 arguments.connection：

{
  "connection": {
    "targetId": "ws://127.0.0.1:8181/<token>/ws",
    "mode": "auto",
    "host": "localhost",
    "port": 8181,
    "uri": "ws://127.0.0.1:8181/<token>/ws",
    "forceReconnect": false
  }
}

说明：

• targetId 是首选选择器，且必须是完整的 VM websocket URI。
• 不接受旧版 host:port 目标 ID；请使用 URI 目标 ID 或 connection.uri。
• 最安全的选择器是 connection.uri，其值为 Flutter 机器的确切 app.debugPort.wsUri。
• 如果 targetId 查找未命中，但 URI 是完整的令牌化 VM 路径（/<token>/ws），服务会尝试直接连接回退方案。
• CLI exec --args 和守护进程 command/execute / watch/start 接受相同的可选嵌套 connection 对象。
• connect_debug_app 接受相同的 connection 结构。
• 动态注册表工具（fmt_list_client_tools_and_resources、fmt_client_tool、fmt_client_resource）接受相同的可选 connection。
• 资源读取也支持通过查询参数指定目标：targetId、mode、host、port、uri、forceReconnect。
• 工具参数中类似 host/port/uri 的扁平顶层连接别名会被严格模式架构有意拒绝。
• 对于 connect 和 session_start，原生选择器参数（mode、targetId、host、port、uri、force）不能与嵌套的 connection 混用。

避免出错的步骤：

1. 读取机器的 app.debugPort.wsUri。
2. 使用 {"connection":{"uri":"<that exact wsUri>"}}。
3. 如果使用 targetId，请从 availableTargets / discover_debug_apps 中原样复制。

Flutter Web 发现

发现顺序为：

1. Flutter 机器发现（flutter attach --machine）
2. 端口扫描回退方案

CLI 和 MCP 服务均接受：

• --flutter-project-dir
• --flutter-device（例如 chrome）
• --flutter-discovery-timeout-ms
• --scan-ports（例如 8765-8767,9100）
• --prefer-target-label（例如 staging）

端口扫描会识别 dart/flutter 进程。桌面应用会在自己的原生进程中托管 VM 服务，而使用 --no-dds 启动的应用没有 Dart 进程，因此这两者都无法通过进程名称找到。请使用固定的 VM 服务端口启动此类应用（flutter run -d macos --device-vmservice-port=8765），并通过 --scan-ports=8765 将该端口传给扫描器。

同时运行多个调试应用时，可让每个应用通过 MCPToolkitBinding.instance.setAppIdentity(label: 'my_app · staging') 标识自身：发现结果会在每个目标上报告此标签，而 --prefer-target-label 可让自动附加选中一个目标，无需调用方指定端点。此标签仅会在自动附加步骤缩小候选范围，因此现有连接和显式指定连接的目标仍会优先；若没有运行中的应用匹配该值，则会忽略此标签，发现行为与未设置时相同。

仍可使用手动回退方案：

• CLI：--vm-service-uri ws://127.0.0.1:59490/<token>/ws
• MCP 工具/资源调用：arguments.connection.uri

快速开始

📦 从 GitHub 安装（当前推荐）

如果你想为项目做贡献，或直接从源代码运行最新版本，请按以下步骤操作：

1. 克隆代码库：

   git clone https://github.com/Arenukvern/mcp_flutter
   cd mcp_flutter
   

2. 安装并构建依赖项：

   make install
   

   此命令会安装 pubspec.yaml 中列出的所有必要依赖项，然后构建 MCP 服务。

3. 将 mcp_toolkit Package 添加到你的 Flutter 应用：

   mcp_toolkit Package 会在你的 Flutter 应用中提供必要的服务扩展。你需要将它添加到应用的 pubspec.yaml 中。

   在 Flutter 应用目录中运行此命令，以添加 mcp_toolkit Package：

   flutter pub add mcp_toolkit
   

   或手动将其添加到 pubspec.yaml：

   dependencies:
     flutter:
       sdk: flutter
     # ... other dependencies
     mcp_toolkit: ^3.0.0
   

   然后在 Flutter 应用目录中运行 flutter pub get。

4. 在应用中初始化： 在 Flutter 应用的 main.dart 文件（或同等入口文件）中，初始化桥接绑定：

   import 'package:flutter/material.dart';
   import 'package:mcp_toolkit/mcp_toolkit.dart'; // Import the package
   import 'dart:async';
   
   Future<void> main() async {
     runZonedGuarded(
       () async {
         WidgetsFlutterBinding.ensureInitialized();
         MCPToolkitBinding.instance
            ..initialize() // Initializes the Toolkit
            ..initializeFlutterToolkit(); // Adds Flutter related methods to the MCP server
         runApp(const MyApp());
       },
       (error, stack) {
         // You can place it in your error handling tool, or directly in the zone. The most important thing is to have it - otherwise the errors will not be captured and MCP server will not return error results.
         MCPToolkitBinding.instance.handleZoneError(error, stack);
       },
     );
   }
   
   // ... rest of your app code
   

5. 以调试模式启动 Flutter 应用

   flutter run --debug --machine --host-vmservice-port=8181 -d macos
   

   根据你的设备调整 -d。优先使用机器输出中的准确 app.debugPort.wsUri，并将其填入 arguments.connection.uri 或 connection.targetId。

6. 🛠️ 将 Flutter MCP Toolkit 添加到你的 AI 客户端

   推荐方式（技能 + MCP 配置）：

   flutter-mcp-toolkit init claude-code   # or: cursor | codex | cline | agents-skills
   

   通过开放的 Agent Skills 生态，仅安装技能：

   npx skills add Arenukvern/mcp_flutter -a cursor -y
   

   有关安装路径、锁文件和 skills.sh，请参阅 docs/ai_agents/overview.mdx。

   手动配置 mcpServers JSON（高级方式——在无法使用 init 时采用）：

   在 mcpServers 下使用注册表键 flutter-mcp-toolkit（标准键）。如果你的配置早于重命名，仍可使用 flutter-inspector 这个 旧键。该字符串 仅 是一个 mcpServers ID，不是 Claude Code 子 Agent 名称。捆绑的运行时子 Agent 为 flutter-mcp-toolkit-runtime（plugin/agents/flutter-mcp-toolkit-runtime.md）。

   推荐的服务参数：--resources、--images、--dynamics（资源和图像默认启用；--dynamics 会启用动态注册表）。

   本地开发说明（GitHub 安装）：

   如果你从 GitHub 安装并在本地构建，请将 command 指向 mcp_server_dart/build/flutter-mcp-toolkit-server。请参阅上文的 从 GitHub 安装。

   Cline 配置

   1. 添加到你的 .cline/config.json：

      {
        "mcpServers": {
          "flutter-mcp-toolkit": {
            "command": "/path/to/your/cloned/mcp_flutter/mcp_server_dart/build/flutter-mcp-toolkit-server",
            "args": [
              "--dart-vm-host=localhost",
              "--dart-vm-port=8181",
              "--resources",
              "--images",
              "--dynamics"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   2. 重启 Cline
   3. Flutter MCP toolkit 工具将在对话中可用
   4. 试试：“请为我的应用截取一张屏幕截图”（MCP 工具使用 fmt_ 前缀，例如 fmt_get_screenshots）

   Cursor 配置

   徽章

   安装服务（点击后在 Cursor 中编辑路径）：

   

   注意：安装后请修正 command 路径。

   手动配置

   1. 打开 Cursor 设置

   2. 转到 Features 选项卡

   3. 在“Model Context Protocol”下添加服务：

      {
        "mcpServers": {
          "flutter-mcp-toolkit": {
            "command": "/path/to/your/cloned/mcp_flutter/mcp_server_dart/build/flutter-mcp-toolkit-server",
            "args": [
              "--dart-vm-host=localhost",
              "--dart-vm-port=8181",
              "--resources",
              "--images",
              "--dynamics"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   4. 重启 Cursor

   5. 打开 Agent 面板（macOS 上按 cmd + L）

   6. 在 MCP 通信中，工具调用使用 fmt_* 名称（例如 fmt_capture_ui_snapshot）。

   Claude 配置

   1. 添加到你的 Claude 配置文件：

      {
        "mcpServers": {
          "flutter-mcp-toolkit": {
            "command": "/path/to/your/cloned/mcp_flutter/mcp_server_dart/build/flutter-mcp-toolkit-server",
            "args": [
              "--dart-vm-host=localhost",
              "--dart-vm-port=8181",
              "--resources",
              "--images",
              "--dynamics"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   2. 重启 Claude
   3. Flutter MCP toolkit 工具即可使用
   4. 试试：“请为我的应用截取一张屏幕截图”

开发

命令行选项

./build/flutter-mcp-toolkit-server [options]

Options:
  --dart-vm-host                Host for Dart VM connection (default: localhost)
  --dart-vm-port                Port for Dart VM connection (default: 8181)
  --resources                   Enable resources support (default: true)
  --images                      Enable images support (default: true)
  --save-images        Save captured images as files in temporal folder instead of returning base64 data (default: false)
  --dumps                       Enable dumps support (default: false)
  --await-dnd                   Wait until DND connection is established (default: false). Do not use with Windsurf. Workaround for MCP Clients which don't support tools updates. Important: some clients doesn't support it. Use with caution. (disable for Windsurf, works with Cursor)
  --log-level                   Logging level (default: critical)
  --environment                 Environment (default: production)
  -h, --help                    Show usage text

图像文件保存模式

启用 --save-images 后，服务将：

• 将所有捕获的屏幕截图保存为 PNG 文件，存放在当前工作目录下的 .mcp_screenshots 文件夹中
• 返回文件 URL（file://），而不是 base64 编码的图像数据
• 自动清理超过 24 小时的屏幕截图
• 使用带时间戳的文件名，例如 screenshot-2025-01-27T10-30-15.123Z.png

此模式适用于：

• 使用更偏好文件引用而非 base64 数据的 AI 工具
• 需要保留屏幕截图以供后续分析
• 避免在响应中包含较大的 base64 字符串，以减少内存使用

基本用法

1. 以调试模式启动 Flutter 应用：

   flutter run --debug --dart-vm-host=localhost --dart-vm-port=8181
   

2. 运行 MCP 服务：

   ./build/flutter-mcp-toolkit-server