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

{
  "claude.mcpServers": {
    "software-design-mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"]
    }
  }
}

{
  "mcpServers": {
    "software-design-mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"]
    }
  }
}

{
  "mcpServers": {
    "software-design-mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/software-design-mermaid-mcp/dist/server/index.js"]
    }
  }
}

✨ Features

🧩 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

🏗️ 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 — use it however you want.