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:

Get a FlutterFlow API token from FlutterFlow > Profile > Account Settings > API Token (requires a paid FlutterFlow subscription)

Add the MCP server to your AI client:

bash

# 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>" } }

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

Tool	Purpose
`list_projects`	List all FF projects accessible to your API token
`list_project_files`	List YAML file keys in a project (supports prefix filter)
`list_pages`	List pages with human-readable names, scaffold IDs, and folders
`search_project_files`	Search file keys by keyword, prefix, or regex
`sync_project`	Download all project YAML to local cache for fast reads

Reading & Understanding

Tool	Purpose
`get_page_by_name`	Fetch full page YAML by human-readable name
`get_project_yaml`	Fetch specific YAML file(s) by file key
`get_page_summary`	Quick page overview: widget tree, actions, params (cache-based)
`get_component_summary`	Quick component overview: widget tree, params (cache-based)
`find_component_usages`	Find all pages/components that use a given component
`find_page_navigations`	Find all actions that navigate to a given page

Configuration & Settings

Tool	Purpose
`get_theme`	Theme colors, typography, breakpoints, widget defaults
`get_app_state`	App state variables, constants, environment settings
`get_api_endpoints`	API endpoint definitions (method, URL, headers, response)
`get_data_models`	Data structs, enums, Firestore collections, Supabase tables
`get_custom_code`	Custom actions, functions, widgets, AI agents (read-only)
`get_general_settings`	App Details, App Assets, Nav Bar & App Bar
`get_project_setup`	Firebase, Languages, Platforms, Permissions, Dependencies
`get_app_settings`	Authentication, Push Notifications, Deployment settings
`get_in_app_purchases`	Stripe, Braintree, RevenueCat, Razorpay config
`get_integrations`	Supabase, SQLite, GitHub, Algolia, Google Maps, AdMob, etc.

Editing & Documentation

Tool	Purpose
`get_editing_guide`	Get recommended workflow and docs for a specific editing task
`get_yaml_docs`	Search/retrieve YAML reference docs by topic or file path
`validate_yaml`	Validate YAML content before pushing changes
`update_project_yaml`	Push validated YAML changes to the FF project

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

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).
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.
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.
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.
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.
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.
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:

When you need...	Call
Widget schema (Button, Text, Container, etc.)	`get_yaml_docs(topic: "Button")`
Action chains, triggers, navigation	`get_yaml_docs(topic: "actions")`
Data binding, variable sources	`get_yaml_docs(topic: "variables")`
Colors, typography, dimensions	`get_yaml_docs(topic: "theming")`
Creating components from scratch	`get_yaml_docs(topic: "create component")`
Editing workflows and anti-patterns	`get_yaml_docs(topic: "editing")`
Data structs, enums, collections	`get_yaml_docs(topic: "data")`
Full docs index	`get_yaml_docs()`
Guided workflow for a specific task	`get_editing_guide(task: "change the button color")`

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