claude-mermaid

Purpose

claude-mermaid is an MCP (Model Context Protocol) server for rendering Mermaid diagrams in Claude Code, with live reload functionality and a built-in expert guidance skill. It automatically renders diagrams in the browser and updates in real time as you make changes, making it suitable for iterative diagram development and documentation workflows.

Main Capabilities

• Live Reload: When you edit a diagram, the diagram in the browser refreshes automatically.
• Multiple Save Formats: Can be exported as SVG, PNG, or PDF.
• Themes: You can choose from the default, forest, dark, or neutral themes.
• Customizable: You can control dimensions, scaling, and background color.
• Interactive Preview: You can drag to pan the diagram, use browser zoom, and reset the position with one click.
• Browser Export: You can download SVG or PNG directly from the preview interface.
• Multiple Previews: Use preview_id to work with multiple diagrams at the same time.
• Persistent Working Files: Live previews are stored under ~/.config/claude-mermaid/live .
• Built-in Skill: Includes a Claude skill that provides best practices and expert guidance for creating diagrams.

Installation Methods

Plugin Installation (Recommended)

Add the marketplace in Claude Code and install the plugin, then restart Claude Code to activate the plugin.

Verify Installation:

Plugin installation: The MCP server is configured automatically; you only need to verify that mermaid appears in the MCP server list.

npm installation: The MCP server must be configured manually; after verification it should display mermaid: claude-mermaid - ✓ Connected.

Configuration for Other MCP Clients

Although this server is optimized for Claude Code, it can also be used with any MCP-compatible client, such as Codex, Cursor, Cline (VSCode extension), Windsurf, Gemini CLI, and others. For any MCP-compatible client, use the standard configuration; the command claude-mermaid should be in PATH after installation.

Note: Some clients may require the full path to the executable. You can find the path via which claude-mermaid(Unix/macOS) or where claude-mermaid(Windows), and use the absolute path in the configuration.

Usage

Simply ask Claude Code to create a Mermaid diagram naturally. When installed as a plugin, the built-in mermaid-diagrams skill provides expert guidance, best practices, and automatic workflow management.

Tools and Parameters:

The MCP server exposes two tools:

• mermaid_preview: Render and open a live preview

  • diagram(string, required): Mermaid diagram code
  • preview_id(string, required): Identifier for this preview session, used to work with multiple diagrams at the same time (such as architecture, flow)
  • format(string, default svg): Optional svg, png, pdf. Live preview supports only svg.
  • theme(string, default default): Optional default, forest, dark, neutral.
  • background(string, default white): Background color, for example transparent, white, #F0F0F0.
  • width(number, default 800): Diagram width (pixels).
  • height(number, default 600): Diagram height (pixels).
  • scale(number, default 2): Scaling factor, used for higher-quality output.

• mermaid_save: Save the current live diagram to the specified path

  • save_path(string, required): Target path (such as ./docs/diagram.svg).
  • preview_id(string, required): Must match the preview_id used in mermaid_preview.
  • format(string, default svg): optional svg, png, pdf. If the live working file for that format does not yet exist, it will be rendered on demand before saving.

How live reload works:

1. First render: open in the browser http://localhost:3737/{preview_id}
2. Make changes: edit the diagram via Claude Code
3. Auto-refresh: the browser detects changes via WebSocket and reloads
4. Status indicator: green dot = connected, red dot = reconnecting

The live server uses ports 3737-3747 and will automatically find an available port.

Live preview controls:

• Pan: click and drag the diagram to move it
• Zoom: use browser zoom (Ctrl/Cmd + +/- or trackpad pinch zoom)
• Reset position: click the ⊙ button in the status bar to re-center the diagram
• Export: click the ⬇ button to download SVG or PNG

The live preview only supports the svg format; there is no live reload when rendering PNG/PDF.

For sequence diagrams, Mermaid does not support using style directives inside a sequenceDiagram.

Standalone server:

You can use the --serve flag to start the preview server without using an AI agent, which opens the diagram library in the browser, containing all previously rendered diagrams, suitable for browsing and exporting diagrams outside of a Claude Code session.

When to use

• Iterative diagram development
• Documentation workflows
• Scenarios where multiple diagrams need to be maintained at the same time
• Diagrams that need to be exported in multiple formats (SVG, PNG, PDF)

Limitations

• The live preview only supports the svg format.
• Sequence diagrams do not support using style directives inside a sequenceDiagram.
• Some clients may require the full path to the executable.

Troubleshooting

• Error: Cannot find package 'puppeteer': This is a rare environment-specific issue. You can try installing npm install -g claude-mermaidglobally, or reinstalling the plugin (/plugin uninstall claude-mermaid, then /plugin install claude-mermaid@claude-mermaid).
• Server not connected:
• Permission denied errors:
• Port already in use: The server uses ports 3737-3747 and will automatically find an available port. You can use lsof -i :3737-3747 to check what is occupying them.
• Diagram not rendering or live reload not working: Server logs are located at ~/.config/claude-mermaid/logs/, where mcp.log records tool requests and diagram rendering, andweb.log records HTTP/WebSocket connections and live reloads. Debug logging can be enabled in the MCP configuration. Available log levels: DEBUG, INFO (default), WARN, ERROR, OFF.

Other information

• Contributions are welcome; you can submit a Pull Request.
• License: MIT, see the LICENSE file for details.
• Related project: preview-skills—preview skills for visualizing files (markdown, csv, json, mermaid, etc.) in the browser.
• Hosted deployment is available on Fronteir AI.