# figma-flow-mcp

Describe a process to Claude and get a clean, automatically laid-out flowchart drawn straight onto your Figma canvas.

![figma-flow drawing a flowchart in Figma](docs/demo.gif)

## How it works

```mermaid
flowchart LR
    claude["Claude<br/>(Claude Code or Claude Desktop)"] -- "MCP over stdio" --> server["figma-flow MCP server<br/>validation + dagre layout"]
    server -- "WebSocket<br/>ws://localhost:3055" --> plugin["figma-flow Figma plugin"]
    plugin --> canvas["Figma canvas"]
```

1. Claude calls `create_flowchart` with the chart's structure only: nodes, edges and labels, no coordinates.
2. The MCP server validates it. It then asks the plugin to measure every label in Figma, so each shape fits its text.
3. The server lays the chart out top to bottom with [dagre](https://github.com/dagrejs/dagre).
4. The plugin draws the shapes, arrows and labels in a new frame.

The plugin's window holds the WebSocket connection, so it stays open while you work.

## Features

- **Plain-language charts.** Describe a process and Claude picks the steps, decisions and branches.
- **Automatic layout.** Claude never sends coordinates; dagre arranges the chart top to bottom, including loops.
- **Standard flowchart shapes,** each sized to fit its label:
  - pills for `start` and `end`
  - rectangles for `process` steps
  - diamonds for `decision`s
  - parallelograms for `input_output`
- **Labeled arrows,** such as "Yes" and "No" on decision branches.
- **One frame per chart,** named after its title and placed to the right of earlier charts. The viewport zooms to it.
- **Clear errors.** Invalid input names the bad node or edge, and the tools tell you when the plugin isn't connected.
- **Safe cleanup.** `clear_canvas` removes only what figma-flow drew.
- **Local only.** The WebSocket bridge listens on `127.0.0.1` and nothing leaves your machine.

Arrows are vector paths, so they don't follow a shape you move by hand. Figma's connector API only exists in FigJam.

## Tools

| Tool | What it does | Example prompt |
| --- | --- | --- |
| `create_flowchart` | Draws a flowchart from a title, nodes and edges | "Draw a flowchart of a password reset flow" |
| `clear_canvas` | Removes every chart figma-flow drew on the current page | "Clear the flowcharts from this page" |
| `draw_demo_flowchart` | Draws a sample login flow to check the setup | "Draw the demo flowchart" |
| `get_status` | Reports whether the Figma plugin is connected | "Is the Figma plugin connected?" |
| `ping` | Checks that the MCP server is running | "Ping the figma-flow server" |

## Requirements

- [Node.js](https://nodejs.org/) 18 or newer
- The [Figma desktop app](https://www.figma.com/downloads/). Development plugins can't be imported in the browser.
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Claude Desktop](https://claude.ai/download)

## Setup

1. **Clone the repository**

   ```bash
   git clone https://github.com/Sanil-Gokarn/figma-flow-mcp.git
   cd figma-flow-mcp
   ```

2. **Install dependencies**

   ```bash
   npm install
   ```

3. **Build the server and the plugin**

   ```bash
   npm run build
   ```

4. **Import the plugin into Figma.** In the Figma desktop app, open a design file. Choose **Plugins → Development → Import plugin from manifest…** and pick `plugin/manifest.json`.

5. **Run the plugin.** Choose **Plugins → Development → figma-flow**. A small window opens; keep it open. It shows **Connected** once Claude's figma-flow server is running, and retries every 2 seconds until then.

6. **Connect Claude.**

   - **Claude Code:** start `claude` in the repository folder. The repo's `.mcp.json` registers the `figma-flow` server; approve it when asked. `/mcp` should list it as connected.
   - **Claude Desktop:** add the server to `claude_desktop_config.json` using the absolute path to your clone, then restart Claude Desktop:

     ```json
     {
       "mcpServers": {
         "figma-flow": {
           "command": "node",
           "args": ["/absolute/path/to/figma-flow-mcp/dist/index.js"]
         }
       }
     }
     ```

7. **Ask for a chart,** for example: "Draw a flowchart for making a cup of tea."

### Changing the port

The bridge listens on port 3055. To use another port, set `PORT` in the server's MCP config:

```json
{
  "mcpServers": {
    "figma-flow": {
      "command": "npx",
      "args": ["tsx", "server/index.ts"],
      "env": { "PORT": "3056" }
    }
  }
}
```

Then change the port in two places in the plugin, and reopen the plugin in Figma:

- `SERVER_URL` in `plugin/ui.html`
- `devAllowedDomains` in `plugin/manifest.json`

## Troubleshooting

### The plugin shows Disconnected, or a tool says "The Figma plugin isn't connected"

- Keep the plugin window open. Closing it drops the connection.
- Check that Claude has the server loaded by asking "Is the Figma plugin connected?". `get_status` also shows the port the server listens on.
- If that port isn't 3055, your environment probably sets `PORT` for something else. Add `"env": { "PORT": "3055" }` to the figma-flow entry in your MCP config.
- Look for WebSocket errors in Figma's console: **Plugins → Development → Show/Hide console**.

### "Port 3055 is already in use"

Another Claude session is already running figma-flow. This could be a second Claude Code window in this folder, or Claude Desktop. Only one session can talk to Figma at a time.

Close the other session, then reconnect figma-flow from `/mcp` or start a new session. To see what holds the port:

```bash
# macOS / Linux
lsof -i :3055
```

```bash
# Windows
netstat -ano | findstr :3055
```

### figma-flow is missing from `/mcp`

- Start Claude Code from the repository folder. `.mcp.json` is project-scoped, so Claude Code only loads it there.
- Approve the server when Claude Code asks. If you declined it earlier, run `claude mcp reset-project-choices` and restart Claude Code.
- Make sure `npm install` has run. Then run `npm run dev` to see any startup errors directly; it waits for MCP input, and Ctrl+C stops it.
- The first `npx` start can be slow. If the server timed out, reconnect it from `/mcp`.

## Development

```bash
npm run dev      # run the server from source with tsx
npm run build    # compile server/ to dist/ and plugin/code.ts to plugin/code.js
npm run check    # type-check the server and the plugin
```

- `server/`: the MCP server. `index.ts` holds the tools, `bridge.ts` the WebSocket bridge, `layout.ts` the dagre layout and `flowchart.ts` the input schema and validation.
- `plugin/`: the Figma plugin. `code.ts` draws on the canvas; `ui.html` holds the WebSocket connection.

## Roadmap

- [ ] Swimlanes
- [ ] Mermaid import
- [ ] Editing existing charts

## License

[MIT](LICENSE) © Sanil Gokarn