Flowchart MCP
by Zafer-Liu
README.md
# Flowchart MCP
<!-- Badges -->
<div align="center">
[](https://modelcontextprotocol.io)
[](https://nodejs.org)
[](LICENSE)
[](https://www.typescriptlang.org)
[](https://reactflow.dev)
[](#)
[](https://github.com/Zafer-Liu/Flowchart_MCP/stargazers)
[](https://github.com/Zafer-Liu/Flowchart_MCP/network/members)
[](https://github.com/Zafer-Liu/Flowchart_MCP/watchers)
</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](#english) · [中文](README_zh.md)*
</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
```bash
git clone https://github.com/Zafer-Liu/Flowchart_MCP.git
cd Flowchart_MCP
npm install
```
### 2. Build
```bash
npm run build
```
### 3. Configure Your MCP Client
**OpenClaw** — `openclaw.json`:
```json
{
"mcpServers": {
"flowchart": {
"command": "node",
"args": ["D:/path/to/Flowchart_MCP/dist/server.js"]
}
}
}
```
**Claude Desktop** — `~/.config/claude-desktop/mcp.json`:
```json
{
"mcpServers": {
"flowchart": {
"command": "node",
"args": ["/absolute/path/to/Flowchart_MCP/dist/server.js"]
}
}
}
```
**Cursor** — Settings → MCP Servers:
```json
{
"mcpServers": {
"flowchart": {
"command": "node",
"args": ["/absolute/path/to/Flowchart_MCP/dist/server.js"]
}
}
}
```
### 4. Run
```bash
# 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.
```json
{ "title": "User Authentication Flow" }
```
**Returns:**
```json
{
"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.
```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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{ "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
```bash
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](LICENSE).
---
<div align="center">
⭐ Stars · 🍴 Forks · 👁 Watchers are welcome!
[](https://github.com/Zafer-Liu/Flowchart_MCP/stargazers)
[](https://github.com/Zafer-Liu/Flowchart_MCP/network/members)
</div>
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessWithin a week