Software Design Mermaid Mcp

🎨 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.

[](https://github.com/wzh4464/software-design-mermaid-mcp/actions/workflows/test.yml) [](LICENSE) [](https://modelcontextprotocol.io) [](#) [](#)

[Getting Started](#-getting-started) · [Features](#-features) · [How It Works](#-how-it-works) · [Contributing](#-contributing)

---

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 ──────────>│
    ││
    │                          │                            │
    │                          │          user drags nodes, │
    │                          │          edits labels,     │
    │                          │          draws connections │
    │                          │                            │
    │                          ││                            │
    ││  (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 FlowDiagram objects
• 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](LICENSE) — use it however you want.

---

If this saves you time designing software, consider giving it a ⭐

Made with React Flow · MCP SDK · dagre

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wzh4464
• Source: wzh4464/software-design-mermaid-mcp
• License: MIT
• Homepage: https://github.com/wzh4464/software-design-mermaid-mcp

Install and usage instructions live in the source repository linked above.