# FlutterFlow MCP Server

A custom [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI coding agents like [Claude Code](https://claude.ai/claude-code) to your [FlutterFlow](https://flutterflow.io/) projects.

Browse, inspect, and modify your FlutterFlow projects directly from your AI assistant — no copy-pasting YAML or switching between tabs.

## Features

- **20 tools** for full project management
- **Local caching** — syncs your project once, then works offline
- **Safe editing workflow** — validate YAML before pushing changes
- **Code export** — download the full Flutter source code to your machine
- **Firebase deployment** — deploy Firestore rules and indexes
- **100% open source** — you control every line of code

## Quick Start

### 1. Install

```bash
git clone https://github.com/erniecode/flutterflow-mcp.git
cd flutterflow-mcp
npm install
npm run build
```

### 2. Get your FlutterFlow API Token

1. Go to [FlutterFlow Account Settings](https://app.flutterflow.io/account)
2. Generate an API token (requires a paid FlutterFlow subscription)

### 3. Add to Claude Code

Run this command in your terminal:

```bash
claude mcp add flutterflow --scope user -- node /path/to/flutterflow-mcp/dist/index.js
```

Then add your API token to the MCP config in `~/.claude.json`:

```json
{
  "mcpServers": {
    "flutterflow": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/flutterflow-mcp/dist/index.js"],
      "env": {
        "FLUTTERFLOW_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### 4. Restart Claude Code

The FlutterFlow tools will now be available. Try asking:

> "List my FlutterFlow projects"

## Available Tools

### Project Management

| Tool | Description |
|------|-------------|
| `list_projects` | List all FlutterFlow projects accessible with your API token |
| `sync_project` | Download and cache all YAML files for a project locally |
| `list_files` | List all YAML file keys in a project |
| `search_files` | Search cached file keys by prefix (e.g. `page/`, `component/`) |

### Pages & Components

| Tool | Description |
|------|-------------|
| `list_pages` | List all pages in a project |
| `get_page` | Get the full YAML content of a specific page |
| `get_page_summary` | Get a high-level summary of a page's structure |

### Project Configuration

| Tool | Description |
|------|-------------|
| `get_theme` | Get theme configuration (colors, typography, breakpoints) |
| `get_app_state` | Get global app state variables |
| `get_settings` | Get general project settings |
| `get_api_endpoints` | List REST API endpoints defined in the project |
| `get_data_models` | Get data models, structs, enums, and database collections |
| `get_custom_code` | Get custom actions, functions, and widgets |

### YAML Operations

| Tool | Description |
|------|-------------|
| `get_yaml` | Get raw YAML content of any file by key |
| `validate_yaml` | Validate YAML changes before applying (always do this first!) |
| `update_yaml` | Push YAML changes to FlutterFlow (irreversible!) |
| `clear_cache` | Clear the local cache for a project |

### CLI Tools (requires `flutterflow_cli`)

| Tool | Description |
|------|-------------|
| `check_cli` | Check if the FlutterFlow CLI is installed |
| `export_code` | Export/download Flutter source code from a project |
| `deploy_firebase` | Deploy Firebase configuration for a project |

To use CLI tools, install the FlutterFlow CLI:

```bash
dart pub global activate flutterflow_cli
```

## Typical Workflow

```
1. list_projects          → find your project ID
2. sync_project           → cache all files locally
3. list_pages             → see what pages exist
4. get_page_summary       → understand a page's structure
5. get_yaml               → read the full YAML
6. validate_yaml          → check your changes are valid
7. update_yaml            → push changes to FlutterFlow
```

## Architecture

```
src/
  index.ts              → MCP server entry point (stdio transport)
  api/
    flutterflow.ts      → FlutterFlow REST API client
  tools/
    projects.ts         → Project management tools
    pages.ts            → Page/component exploration tools
    config.ts           → Theme, settings, data model tools
    yaml-ops.ts         → YAML read/validate/update tools
    cli.ts              → FlutterFlow CLI wrapper tools
  utils/
    cache.ts            → Local file-based caching layer
```

## FlutterFlow API

This server uses the [FlutterFlow Project API](https://docs.flutterflow.io/resources/projects/settings/project-apis/):

- **Base URL:** `https://api.flutterflow.io/v2`
- **Auth:** Bearer token
- **Endpoints:** `listProjects`, `listPartitionedFileNames`, `projectYamls`, `validateProjectYaml`, `updateProjectByYaml`

## Safety Notes

- `update_yaml` modifies your **live FlutterFlow project** and **cannot be undone**
- Always run `validate_yaml` before `update_yaml`
- Start with read-only tools (`list_*`, `get_*`, `sync_*`) to get familiar
- Use a **test project** before working on production projects
- Your API token is stored locally in `~/.claude.json` — never commit this file

## Requirements

- Node.js 18+
- FlutterFlow account with API access (paid plan)
- Claude Code (or any MCP-compatible AI agent)
- Optional: Dart SDK + `flutterflow_cli` for code export/Firebase deploy

## License

MIT

---

Built with Claude Code by [@erniecode](https://github.com/erniecode)