veelenga/claude-mermaid

MCP server for rendering Mermaid diagrams in Claude Code with **live reload** functionality and a built-in skill for expert guidance.
Automatically renders diagrams in your browser with real-time updates as you refine them. Perfect for iterative diagram development and documentation workflows.
✨ Features
- 🔄 **Live Reload** - Diagrams auto-refresh in your browser as you edit
- 🎨 **Multiple Save Formats** - Export to SVG, PNG, or PDF
- 🌈 **Themes** - Choose from default, forest, dark, or neutral themes
- 📐 **Customizable** - Control dimensions, scale, and background colors
- 🪄 **Interactive Preview** - Pan diagrams by dragging, zoom with browser controls, reset position with one click
- ⬇️ **Browser Export** - Download diagrams as SVG or PNG directly from the preview
- 🗂️ **Multiple Previews** - Use preview_id to work on multiple diagrams simultaneously
- 💾 **Persistent Working Files** - Live previews are stored under ~/.config/claude-mermaid/live
- 🤖 **Built-in Skill** - Includes a Claude skill with best practices and expert guidance for creating diagrams
Architecture
Project Architecture Diagram
User Workflow Diagram
Dependencies Diagram
🚀 Quick Start
1. Install
**Plugin Install (Recommended)**
In Claude Code, add the marketplace and install the plugin:
Then restart Claude Code to activate the plugin.
**From npm:**
**From source:**
2. Verify Installation
**Plugin install:** The MCP server is configured automatically. Just verify:
You should see mermaid in the MCP server list.
**npm install:** Configure the MCP server manually:
Then verify:
You should see mermaid: claude-mermaid - ✓ Connected
🔌 Other MCP Client Configurations
While this server is optimized for Claude Code, it can work with any MCP-compatible client. Here's how to configure it for other popular tools:
Codex
Add to your Codex MCP settings file (~/.codex/mcp_settings.json):
Or configure via Codex CLI:
Cursor
Add to your Cursor MCP config file (.cursor/mcp.json or settings):
Or use Cursor's settings UI:
1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to MCP Servers
3. Add a new server with command: claude-mermaid
VSCode with Cline Extension
If using the Cline extension for VSCode:
1. Open VSCode settings (Cmd/Ctrl + ,)
2. Search for "Cline MCP"
3. Add to MCP Settings JSON:
Windsurf
Add to Windsurf's MCP configuration file:
Configuration location varies by platform:
- **macOS:** ~/Library/Application Support/Windsurf/mcp.json
- **Linux:** ~/.config/windsurf/mcp.json
- **Windows:** %APPDATA%\Windsurf\mcp.json
Gemini CLI
Add to Gemini CLI's MCP configuration file (~/.gemini/mcp.json):
Or use the Gemini CLI to configure:
Other MCP Clients
For any MCP-compatible client, use the standard configuration:
The command claude-mermaid should be available in your PATH after installation.
**Note:** Some clients may require the full path to the executable:
- Find the path: which claude-mermaid (Unix/macOS) or where claude-mermaid (Windows)
- Use absolute path in config: "command": "/path/to/claude-mermaid"
💡 Usage
Simply ask Claude Code to create Mermaid diagrams naturally. When installed as a plugin, the built-in mermaid-diagrams skill provides expert guidance, best practices, and automatic workflow management.
Basic Examples
Advanced Examples
**With custom formatting:**
**With specific output format:**
_Note: Browser always shows SVG for live preview, while saving to your chosen format._
**Iterative refinement:**