Flowchart MCP

<!-- Badges --> <div align="center">

</div>

---

<div align="center">

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

English · 中文

</div>

---

✨ 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

Copyright © 2026. Licensed under the Apache License 2.0.

---

<div align="center">

⭐ Stars · 🍴 Forks · 👁 Watchers are welcome!

</div>