Claude Mermaid

What veelenga/claude-mermaid MCP server does

veelenga/claude-mermaid MCP server turns Mermaid diagram definitions into browser previews or saved files. It exposes two MCP tools: mermaid_preview creates or updates a preview session, and mermaid_save writes the current diagram to a specified path. Supported output formats are SVG, PNG, and PDF.

The server is intended for diagram work such as authentication flows, sequence diagrams, deployment pipelines, class diagrams, architecture diagrams, and entity-relationship diagrams. A built-in mermaid-diagrams skill is included when the project is installed as a Claude Code plugin. That skill provides diagram guidance and workflow recommendations, but the MCP tools can also be configured in other MCP clients.

How it works

A preview request includes Mermaid source and a preview_id. The server opens a local browser page at a URL based on that identifier. For SVG previews, the browser receives updates through WebSocket connections and refreshes when the diagram changes. Multiple identifiers allow separate diagrams to be developed at the same time.

The local preview service uses ports 3737 through 3747 and selects an available port. The browser interface supports dragging to pan, browser zoom controls, resetting the diagram position, and downloading SVG or PNG output. Live preview is limited to SVG; PNG and PDF are rendered without live reload.

Working files for live previews are stored below ~/.config/claude-mermaid/live. The browser displays SVG during live preview even when another save format is requested. mermaid_save can render the requested format on demand if a working file for that format does not already exist.

Setup and configuration

Claude Code users can install the plugin from the veelenga/claude-mermaid marketplace repository and restart Claude Code. Another documented route is installing the claude-mermaid npm package globally, then registering claude-mermaid as the MCP command. Installing from source requires cloning the repository, running its npm installation and build steps, and installing the resulting package globally.

The documented executable is claude-mermaid. MCP configuration for Cursor, Windsurf, Cline, and other clients uses that executable as a local command. The project also supports standalone operation with claude-mermaid --serve, which opens a diagram gallery without an AI agent.

Tools and capabilities

mermaid_preview accepts:

• Required Mermaid diagram text and preview_id.
• format: svg, png, or pdf; defaults to SVG.
• theme: default, forest, dark, or neutral.
• background, width, height, and scale settings.

mermaid_save accepts a required save_path and matching preview_id, plus an optional output format. The save identifier must refer to a preview created with mermaid_preview.

Limitations and notes

Live reload applies only to SVG previews. Mermaid sequence diagrams do not support style directives inside sequenceDiagram definitions. The server opens local browser pages and depends on an available port in its configured range. Output paths and preview identifiers must be supplied by the calling workflow.