community-ff-mcp

Prerequisites

This skill requires the community-ff-mcp MCP server to be installed and connected. Before proceeding, check if the list_projects tool is available. If not, the user needs to set up the MCP server first:

1. Get a FlutterFlow API token from FlutterFlow > Profile > Account Settings > API Token (requires a paid FlutterFlow subscription)
2. Add the MCP server to your AI client:

   # Claude Code
   claude mcp add flutterflow -e FLUTTERFLOW_API_TOKEN=<token> -- npx -y community-ff-mcp
   
   # Other clients (Claude Desktop, Cursor, Windsurf) — add to MCP config:
   # { "command": "npx", "args": ["-y", "community-ff-mcp"], "env": { "FLUTTERFLOW_API_TOKEN": "<token>" } }
   

3. Restart your AI client, then verify by calling list_projects

Overview

The FlutterFlow MCP provides 25 tools for reading, inspecting, and editing FlutterFlow projects through YAML. It connects AI assistants to the FlutterFlow Project API, enabling programmatic access to pages, components, themes, actions, data models, and settings. All project data is represented as YAML files that can be fetched, cached locally, validated, and pushed back.

Tool Catalog

Discovery & Exploration

Reading & Understanding

Configuration & Settings

Editing & Documentation

Core Workflows

Discover & Explore a Project

Use this workflow when first connecting to a FlutterFlow project or when you need to understand its structure.

1. list_projects → pick the target projectId
2. sync_project(projectId) → cache all YAML locally for fast reads
3. list_pages(projectId) → see all pages with human-readable names, scaffold IDs, folders
4. get_page_summary(projectId, pageName) → widget tree overview for any page of interest

After syncing, all cache-based tools (get_page_summary, get_component_summary, get_theme, get_app_state, etc.) work without additional API calls.

Read / Inspect a Page or Component

Use this workflow to understand what a page contains, how it is structured, and how it connects to the rest of the app.

1. get_page_summary(projectId, pageName) → quick overview of widget tree, actions, params
2. get_page_by_name(projectId, pageName) → full YAML if you need complete details
3. find_page_navigations(projectId, pageName) → discover what actions navigate here
4. find_component_usages(projectId, componentName) → find everywhere a component is used

For components, use get_component_summary instead of get_page_summary. Component summaries resolve nested component references so you can see the full hierarchy.

Edit an Existing Widget

Use this workflow to modify a specific widget on a page without affecting the rest of the page.

1. get_page_by_name(projectId, pageName) → get the full page YAML
2. Identify the node file key for the target widget (format: page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY)
3. get_project_yaml(projectId, fileName: "page/id-.../node/id-Widget_XXX") → fetch the individual node YAML
4. Modify the YAML — keep inputValue and mostRecentInputValue in sync
5. validate_yaml(projectId, fileKey, content) → check for errors before pushing
6. update_project_yaml(projectId, {fileKey: content}) → push changes

Always edit at the node level. Editing the full page YAML for a single widget change risks overwriting unrelated content and is more error-prone.

Add a New Widget to a Page

Use this workflow when you need to add new widgets to an existing page.

1. get_page_by_name(projectId, pageName) → understand the current widget tree structure
2. get_yaml_docs(topic: "WidgetType") → look up the YAML schema for the widget you want to add
3. Update the page-widget-tree-outline to include a reference to the new widget key
4. Create individual node files for each new widget (one file per widget)
5. validate_yaml → validate the tree outline first, then each node file
6. update_project_yaml → push tree outline + all node files together in one call

Pushing the tree outline and node files in a single call is critical. The server strips inline widget children from the tree outline, so nodes must be separate files.

Create a Reusable Component

Use this workflow to build a new component from scratch.

1. get_yaml_docs(topic: "create component") → get the full walkthrough and required file structure
2. Design component parameters: name, dataType, isNullable for each param
3. Create these files: component metadata, widget-tree-outline, root node (with isDummyRoot: true), child nodes
4. validate_yaml → validate all files before pushing
5. update_project_yaml → push all component files in one call

Remember: the root node of a component must have isDummyRoot: true. Callback triggers use triggerType: CALLBACK with a separate parameterIdentifier field. WidgetProperty params use widgetProperty in parameterPasses, not inputValue.

Critical YAML Rules

1. Sync inputValue and mostRecentInputValue — Both fields must always contain the same value when you set or update them. If you change one, change both. Exceptions: fontWeightValue and fontSizeValue only accept inputValue (they have no mostRecentInputValue field).

2. Use node-level file keys for edits — Target page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY for individual widget edits. Never edit the full page YAML (page/id-Scaffold_XXX) just to change a single widget. Full-page edits risk overwriting unrelated content and are harder to validate.

3. Always validate before pushing — Call validate_yaml before every update_project_yaml call. Validation catches missing node files, unknown fields, invalid enum values, and structural problems. Skipping validation risks corrupting the project.

4. Push tree outline and node files together — When adding new widgets, include the updated page-widget-tree-outline AND all individual node files in a single update_project_yaml call. Widget children embedded inline in the tree outline will be silently stripped by the FlutterFlow server.

5. Column has no mainAxisSize field — To achieve shrink-to-content behavior (equivalent to MainAxisSize.min in Flutter), use minSizeValue: { inputValue: true } on the Column widget instead.

6. AppBar templateType — Only LARGE_HEADER is a confirmed valid value. Do not use STANDARD as it may cause unexpected behavior. Control the AppBar height through the toolbarHeight property instead.

7. Custom code is read-only — Custom actions, functions, widgets, and AI agents cannot be created or edited through the MCP API. Use get_custom_code to read their signatures and source code, but any modifications must be made directly in the FlutterFlow UI. Attempting to push custom code changes will silently corrupt or be ignored.

Anti-Patterns

• Don’t use list_project_files to find pages — It returns raw file keys without human-readable names. Use list_pages instead, which gives you page names, scaffold IDs, and folder assignments.

• Don’t fetch pages one-by-one to browse a project — This is slow and wastes API calls. Use sync_project to cache everything locally first, then use get_page_summary for quick overviews of any page.

• Don’t edit full page YAML for a single widget change — Full-page edits can overwrite other widgets, actions, or parameters. Always use node-level file keys for targeted, safe edits.

• Don’t guess YAML field names or enum values — FlutterFlow YAML has specific field names and valid values that are not always intuitive. Use get_yaml_docs(topic) or get_editing_guide(task) to look up the correct schema before writing YAML.

• Don’t embed widget children inline in the tree outline — The FlutterFlow server silently strips inline children from the page-widget-tree-outline file. Always create separate node files for each widget.

• Don’t push custom code changes through the API — The API silently corrupts or ignores Dart code edits for custom actions, functions, and widgets. These must be edited in the FlutterFlow UI.

Documentation Lookup

The MCP server ships with 21 built-in reference documents. Use these tools to look up schemas, patterns, and conventions before writing YAML:

Always consult the docs before writing YAML. They contain validated schemas, field references, enum values, and real examples.