loading…
Browse all
Software Design Mermaid
FreeNot checkedEnables visual drag-and-drop editing of Mermaid diagrams through Claude, allowing iterative refinement of software architecture designs.
About
Enables visual drag-and-drop editing of Mermaid diagrams through Claude, allowing iterative refinement of software architecture designs.
README
🎨 Mermaid Visual Editor for Claude
Stop describing diagrams. Start designing them.
Turn Claude into a visual software design partner with a drag-and-drop Mermaid editor that opens right in your browser.
Claude generates the diagram, you refine it visually — drag nodes, edit labels, draw connections, then submit back for the next iteration
The Problem
When designing software with Claude, you're stuck in a text-only loop:
You: "Add a cache layer between the API and database"
Claude: *regenerates entire Mermaid diagram from scratch*
You: "No, move the cache node to the left..."
Claude: *guesses what you mean, regenerates again*
It's like directing a painter blindfolded.
The Solution
This MCP server gives Claude a visual canvas. When Claude generates a diagram, it pops open a browser-based editor where you can:
- Drag nodes exactly where you want them
- Edit labels inline with a double-click
- Draw connections between any nodes
- Rearrange everything and submit back to Claude
Claude sees your visual changes and continues the conversation with full context. Design together, visually.
What is MCP? Model Context Protocol lets AI assistants use external tools. This server gives Claude the ability to open a visual diagram editor — no plugins or extensions needed.
⚡ Getting Started
Claude Code (recommended)
git clone https://github.com/wzh4464/software-design-mermaid-mcp.git
cd software-design-mermaid-mcp
npm install && npm run build
claude mcp add software-design-mermaid node $(pwd)/dist/server/index.js
Then just ask Claude:
> Design a microservice architecture for a todo app
Your browser opens automatically with the visual editor. Edit, submit, iterate. ✨
VS Code + Claude Extension
Add to your VS Code settings.json:
{
"claude.mcpServers": {
"software-design-mermaid": {
"command": "node",
"args": ["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"]
}
}
}
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"software-design-mermaid": {
"command": "node",
"args": ["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"]
}
}
}
Cursor
Add to your Cursor MCP settings (.cursor/mcp.json):
{
"mcpServers": {
"software-design-mermaid": {
"command": "node",
"args": ["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"]
}
}
}
Windsurf / Cline / Other MCP Clients
Any MCP-compatible client can use this server. The configuration pattern is the same:
- Command:
node - Args:
["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"] - Transport: stdio
Refer to your client's documentation for the exact config file location.
✨ Features
| Feature | Description | |
|---|---|---|
| 🖱️ | Drag-and-Drop Canvas | Full React Flow editor with zoom, pan, minimap, grid snapping |
| 🔷 | 5 Shapes × 3 Edge Types | Rectangle, rounded, diamond, circle, stadium + arrow, dotted, thick |
| 📦 | Subgraphs & Auto-Layout | Group nodes into nested subgraphs; dagre auto-arranges (TD/LR/BT/RL) |
| 📝 | Live Mermaid Preview | See Mermaid code update in real-time as you edit |
| 🔄 | Multi-Round Iteration | Edit → Submit → Claude refines → Edit again. True visual collaboration. |
| ⏪ | Undo / Redo | Full history with Ctrl+Z / Ctrl+Y |
| ⚙️ | Zero Config | Auto-finds an open port and launches your browser |
See: Horizontal layout with subgraphs
🧩 How It Works
Claude MCP Server Browser Editor
│ │ │
│── show_diagram() ───────>│ │
│ │── starts HTTP server ─────>│
│ │── opens browser ──────────>│
│<── { url, success } ─────│ │
│ │ │
│ │<── polls /api/diagram ─────│
│ │── returns diagram ────────>│
│ │ │
│ │ user drags nodes, │
│ │ edits labels, │
│ │ draws connections │
│ │ │
│ │<── POST /api/submission ───│
│── get_diagram_feedback()>│ │
│<── updated mermaid code ─│ │
│ │ │
│── show_diagram() ───────>│ (Claude sends new version)│
│ ...iterate... │ │
MCP Tools
| Tool | What it does |
|---|---|
show_diagram |
Opens the visual editor with a Mermaid flowchart |
get_diagram_feedback |
Gets the user's visual edits back as Mermaid code |
close_diagram |
Closes the editor session |
🏗️ Architecture
TypeScript monorepo with npm workspaces:
software-design-mermaid-mcp/
├── shared/ # Mermaid parser & serializer (bidirectional)
├── src/ # MCP server (stdio) + HTTP server (REST API)
├── editor/ # React Flow visual editor
└── dist/ # Pre-built artifacts
- Parser: Full Mermaid flowchart syntax → structured
FlowDiagramobjects - Serializer:
FlowDiagram→ valid Mermaid code (round-trip safe) - Editor: React 19 + React Flow 12 with custom node/edge renderers
🧑💻 Development
npm install # Install all workspace dependencies
npm test # Run all tests (42 tests, 4 suites)
npm run build # Build shared → server → editor
npm run dev:editor # Editor dev mode with hot reload
🤝 Contributing
Contributions welcome! Some ideas to get started:
- 📊 Sequence diagram support — extend beyond flowcharts
- 🎨 Theme customization — dark/light modes, color schemes
- 📸 Export options — PNG, SVG, PDF export from the editor
- 👥 Collaborative editing — multiple users on the same diagram
- 🔶 More node shapes — hexagon, parallelogram, trapezoid
Please open an issue first to discuss what you'd like to change.
📄 License
MIT — use it however you want.
If this saves you time designing software, consider giving it a ⭐
Made with React Flow · MCP SDK · dagre
How to install
Run in your terminal:
claude mcp add software-design-mermaid-mcp -- npx 
