Flowchart MCP

A Model Context Protocol server that empowers AI assistants to create, edit, and export flowcharts through a local web-based editor.

English · 中文

✨ Features

| Feature | Description | |---------|-------------| | 14 MCP Tools | Full CRUD for nodes and edges, auto-layout, themes, export, diagram introspection | | Visual Editor | React Flow canvas — drag nodes, resize, connect via handles, zoom/pan, minimap | | 7 Node Shapes | Rectangle, Diamond, Ellipse, Rounded Rectangle, Parallelogram, Cylinder, Hexagon | | Edge Styling | Solid / Dashed / Dotted; optional arrows at start/end; custom labels and colors | | Auto Layout | Layered graph layout in 4 directions: Top→Bottom, Left→Right, Bottom→Top, Right→Left | | 4 Color Themes | Default (blue), Dark, Pastel, Colorful — one call to restyle all nodes | | Real-time Sync | All editor changes are pushed to the MCP server via WebSocket within ~600ms | | Export | PNG (Puppeteer rasterization), SVG, and native JSON | | In-editor Editing | Drag shapes from the left panel, right-click context menus, collapsible sidebar |

🏗️ Architecture

                        AI Assistant
                             │
                     MCP JSON-RPC (stdio)
                             │
          ┌──────────────────▼──────────────────┐
          │         Flowchart MCP Server          │
          │                                         │
          │  ┌──────────┐  ┌──────────┐  ┌─────────┐│
          │  │   MCP    │  │  In-Mem  │  │ Express ││
          │  │ SDK      │◄─┤  Store   │◄─┤ HTTP    ││
          │  │ Stdio    │  │          │  │ :3742   ││
          │  └──────────┘  └──────────┘  └─────────┘│
          │                              ┌─────────┐│
          │                     WS push  │ Express ││
          │                              │ WS      ││
          └──────────────────────────────┴────┬─────┘
                                             │
                        ┌────────────────────▼──────────┐
                        │     React Flow Web Editor      │
                        │                                │
                        │  ┌──────────┐ ┌─────┐ ┌──────┐ │
                        │  │  Shapes  │ │     │ │      │ │
                        │  │  Panel   │ │Canvas│ │Sidebar│
                        │  └──────────┘ │     │ │      │ │
                        │               └─────┘ └──────┘ │
                        │  ┌────────┐ ┌────────┐        │
                        │  │Controls│ │ MiniMap│        │
                        │  └────────┘ └────────┘        │
                        └────────────────────────────────┘

🚀 Quick Start

Prerequisites

Node.js ≥ 20.14.0
Chrome / Chromium (required for PNG export via Puppeteer)

1. Install

git clone https://github.com/Zafer-Liu/Flowchart_MCP.git
cd Flowchart_MCP
npm install

2. Build

npm run build

3. Configure Your MCP Client

OpenClaw — openclaw.json:

{
  "mcpServers": {
    "flowchart": {
      "command": "node",
      "args": ["D:/path/to/Flowchart_MCP/dist/server.js"]
    }
  }
}

Claude Desktop — ~/.config/claude-desktop/mcp.json:

{
  "mcpServers": {
    "flowchart": {
      "command": "node",
      "args": ["/absolute/path/to/Flowchart_MCP/dist/server.js"]
    }
  }
}

Cursor — Settings → MCP Servers:

{
  "mcpServers": {
    "flowchart": {
      "command": "node",
      "args": ["/absolute/path/to/Flowchart_MCP/dist/server.js"]
    }
  }
}

4. Run

# Production
npm start

# Development (tsx hot-reload)
npm run dev

On first run, the server automatically starts a background web server at http://localhost:3742 — no manual configuration needed.

🛠️ MCP Tools Reference

Diagram Management

`create_diagram`

Creates a new flowchart and returns the editor URL.

{ "title": "User Authentication Flow" }

Returns:

{
  "diagram_id": "uuid-string",
  "title": "User Authentication Flow",
  "editor_url": "http://localhost:3742/?diagram=uuid-string"
}

`open_editor` · `get_diagram` · `list_diagrams`

open_editor — Get the editor URL for an existing diagram
get_diagram — Read the full diagram state as JSON
list_diagrams — List all diagrams in the current session

`export_diagram`

Export the diagram to PNG, SVG, or JSON.

{
  "diagram_id": "uuid-string",
  "format": "png" | "svg" | "json",
  "output_path": "/path/to/output.png"
}

Node Operations

`add_node`

Add a node with custom shape, position, and colors.

{
  "label": "Process Order",
  "shape": "rectangle",          // rectangle | diamond | ellipse | rounded | parallelogram | cylinder | hexagon
  "x": 100,
  "y": 100,
  "width": 160,
  "height": 60,
  "background_color": "#4A90D9",
  "border_color": "#333333",
  "text_color": "#FFFFFF"
}

`update_node`

Update any property of an existing node: label, shape, position, size, or colors.

`remove_node`

Remove a node and all its connected edges.

Edge Operations

`add_edge`

Create a directed connection between two nodes.

{
  "source": "node-uuid-1",
  "target": "node-uuid-2",
  "label": "yes",
  "style": "solid",       // solid | dashed | dotted
  "arrow_end": "arrow",   // arrow | none
  "arrow_start": "none",  // arrow | none
  "color": "#0052CC"
}

`update_edge` · `remove_edge`

Update or remove an edge.

Layout & Themes

`auto_layout`

Automatically arrange all nodes using a layered graph layout algorithm.

{
  "direction": "TB"   // TB | LR | BT | RL
}

| Direction | Layout | |-----------|--------| | TB | Top → Bottom | | LR | Left → Right | | BT | Bottom → Top | | RL | Right → Left |

`apply_theme`

Apply a preset color theme to all nodes in one call.

{ "theme": "default" }   // default | dark | pastel | colorful

| Theme | Primary | Background | Border | Text | |-------|---------|------------|--------|------| | default | #4A90D9 | #F5F5F5 | #333333 | #000000 | | dark | #1E1E1E | #2D2D2D | #555555 | #FFFFFF | | pastel | #AED6F1 | #FDFEFE | #85C1E9 | #333333 | | colorful | #E74C3C | #F9EBEA | #C0392B | #2C3E50 |

🎨 Web Editor Guide

Editor Layout

┌──────────────────────────────────────────────────────────────────┐
│ Toolbar: [New] [Export▾] [Auto Layout▾] [Theme▾]    [+] [−] [⊡] │
├───────┬──────────────────────────────────────────────┬───────────┤
│       │                                              │           │
│ Shape │          React Flow Canvas                   │  Sidebar  │
│ Panel │   (drag nodes · connect handles · zoom/pan)  │ Properties│
│       │                                              │   Editor  │
│ ───── │                                              │           │
│ Rect  │  ┌──────────┐    ┌──────────┐               │  Node:    │
│ Diam  │  │  Start   │───▶│  Process │               │   Label   │
│ Ellip │  └──────────┘    └──────────┘               │   Shape   │
│ ...   │                    │                        │   Colors  │
│       │               ┌────▼────┐                   │           │
│       │               │Decision │                   │   Edge:   │
│       │               └─────────┘                    │   Label   │
│       │                                              │   Style   │
├───────┴──────────────────────────────────────────────┴───────────┤
│  Status: ● Connected    3 nodes · 2 edges    Updated 14:32:05   │
└──────────────────────────────────────────────────────────────────┘

Interactions

| Action | How | |--------|-----| | Add node | Drag shape from left panel onto canvas | | Connect nodes | Hover node → drag from handle dot to another node | | Select node/edge | Click on it — sidebar shows its properties | | Move node | Drag the node body | | Edit label | Double-click the label on canvas, or use sidebar | | Delete | Select → Delete key | | Context menu | Right-click node / edge / canvas | | Zoom | Mouse wheel or + / − in toolbar | | Fit view | ⊡ button in toolbar | | Resize sidebar | Drag the divider between canvas and sidebar | | Toggle minimap | Click ▼ 缩略图 / ▲ 缩略图 | | Collapse shapes panel | Click ◀ / ▶ toggle at top of left panel |

Real-time Sync

All edits in the browser are synced back to the MCP server via WebSocket (~600ms debounce). When the AI assistant calls get_diagram, it receives the latest user-modified state.

⚙️ Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3742 | HTTP / WebSocket server port | | HOST | localhost | Host to bind |

Standalone Web Server

node dist/web-server-standalone.js
# Starts only the web editor on :3742 (no MCP transport)
# Useful for testing the editor independently

📁 Project Structure

Flowchart_MCP/
├── src/
│   ├── server.ts                  # Entry point — MCP stdio transport, global error handling
│   ├── tools/
│   │   └── index.ts              # All 14 MCP tool definitions (zod schemas + handlers)
│   ├── store.ts                  # In-memory diagram store (Map-based, session-scoped)
│   ├── layout.ts                 # Layered graph auto-layout (Sugiyama-style)
│   ├── export.ts                 # PNG / SVG / JSON export via Puppeteer
│   ├── web-launcher.ts           # Lazy web server startup / lifecycle manager
│   ├── web-server.ts             # Express + WebSocket on :3742
│   └── web-server-standalone.ts  # Standalone web server entry point
├── client/                        # React Flow web editor (Vite build)
│   └── src/
│       ├── App.tsx               # Root editor component, layout, canvas
│       ├── Sidebar.tsx           # Node / edge property editor panel
│       ├── ShapesPanel.tsx       # Draggable shape palette
│       ├── CustomNode.tsx        # Custom React Flow node renderer (7 shapes)
│       ├── ContextMenu.tsx       # Right-click context menu
│       └── types.ts              # Shared TypeScript type definitions
├── dist/                          # Compiled server JS (npm published)
├── package.json
├── tsconfig.json
└── LICENSE

🧰 Tech Stack

| Layer | Technology | |-------|------------| | Protocol | MCP SDK v1.12.0 · StdioServerTransport | | Server Runtime | Node.js · TypeScript · tsx | | HTTP Layer | Express 4 · ws (WebSocket) | | Diagram Storage | In-memory (Map-based, session-scoped) | | Export | Puppeteer 22 (Chromium) | | Frontend | React 18 · React Flow · @xyflow/react · TypeScript | | Build (server) | TypeScript compiler (tsc) | | Build (client) | Vite |

📄 License

⭐ Stars · 🍴 Forks · 👁 Watchers are welcome!

MCP Servers

Flowchart MCP

✨ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

1. Install

2. Build

3. Configure Your MCP Client

4. Run

🛠️ MCP Tools Reference

Diagram Management

`create_diagram`

`open_editor` · `get_diagram` · `list_diagrams`

`export_diagram`

Node Operations

`add_node`

`update_node`

`remove_node`

Edge Operations

`add_edge`

`update_edge` · `remove_edge`

Layout & Themes

`auto_layout`

`apply_theme`

🎨 Web Editor Guide

Editor Layout

Interactions

Real-time Sync

⚙️ Configuration

Environment Variables

Standalone Web Server

📁 Project Structure

🧰 Tech Stack

📄 License

Install Package (if required)

Cursor configuration (mcp.json)

Flowchart MCP

✨ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

1. Install

2. Build

3. Configure Your MCP Client

4. Run

🛠️ MCP Tools Reference

Diagram Management

create_diagram

open_editor · get_diagram · list_diagrams

export_diagram

Node Operations

add_node

update_node

remove_node

Edge Operations

add_edge

update_edge · remove_edge

Layout & Themes

auto_layout

apply_theme

🎨 Web Editor Guide

Editor Layout

Interactions

Real-time Sync

⚙️ Configuration

Environment Variables

Standalone Web Server

📁 Project Structure

🧰 Tech Stack

📄 License

Install Package (if required)

Cursor configuration (mcp.json)

`create_diagram`

`open_editor` · `get_diagram` · `list_diagrams`

`export_diagram`

`add_node`

`update_node`

`remove_node`

`add_edge`

`update_edge` · `remove_edge`

`auto_layout`

`apply_theme`