Claude Mermaid MCP

MCP server for Mermaid diagrams: renders a diagram in the browser with live reload and saves it as SVG, PNG or PDF

221 ★ on the repository
Last commit Nov 13, 2026
MIT

veelenga/claude-mermaidAuthor:Vitalii Elenhaupt

Install

Works in: Claude Code
Codex
Cursor
SourceCraft
Koda
Coddy

Manual install

/plugin marketplace add veelenga/claude-mermaid

Then /plugin install claude-mermaid@claude-mermaid and restart Claude Code; the MCP server is configured automatically.

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

The server launches a headless browser for rendering and a local web server on ports 3737 to 3747
The mermaid_save tool writes a file at a path the agent supplies

This is third-party code. Review the repository files before installing.

What it does

Claude Mermaid is an MCP server that opens a Mermaid diagram in the browser and refreshes the page while you refine the diagram with the agent. The mermaid_preview tool renders it: it takes the diagram code, a preview ID, a format, a theme (default, forest, dark, neutral), a background color, a size and a scale. mermaid_save writes the result to a path as SVG, PNG or PDF. Live preview works for SVG only and runs over a WebSocket on local ports 3737 to 3747. You can pan the diagram with the mouse, zoom with browser controls and download it from the preview window. Several previews run in parallel under different IDs. A bundled skill gives advice on building diagrams, and working files live in ~/.config/claude-mermaid/live.

Who it is for. Developers and technical writers who sketch architecture and sequence diagrams with an agent and want to see the result at once.

Good fit when

An architecture diagram is refined in dialogue and the browser must refresh after every edit
A documentation diagram is saved as SVG, PNG or PDF at a given path
Several diagrams are kept at once, for example architecture and a request flow
The agent needs the bundled skill's advice on good diagram structure

Not a fit when

You need a diagram editor with mouse drawing: diagrams are built as Mermaid code and the mouse only moves the finished picture
The environment has no Node.js or browser: rendering runs through a Node package and opens a page locally
You need live editing of PNG or PDF: live preview works for SVG only

Example request

Draw a sequence diagram of an OAuth login and save it to docs/auth-flow.svg

MCP

Transport: stdio
Authentication: not required

Limitations

The server takes one of the local ports 3737 to 3747 and opens a browser tab on the machine where the agent runs, so on a remote machine without a browser the preview will not open. Rendering uses puppeteer, and in rare environments the package is not found: the README advises installing claude-mermaid globally or reinstalling the plugin. Live preview is available for SVG only; PNG and PDF are built on save.

How to disable. Remove the plugin with /plugin uninstall claude-mermaid or run claude mcp remove mermaid. For an npm install add npm uninstall -g claude-mermaid. Working files can be deleted from ~/.config/claude-mermaid.

FAQ

How do I connect it to Cursor or Codex?

For Codex run codex mcp add mermaid claude-mermaid; for Cursor add a mermaid server with the command claude-mermaid to .cursor/mcp.json. Install the package globally first with npm install -g claude-mermaid.

Which tools does it expose?

Two: mermaid_preview renders a diagram and opens a live preview, mermaid_save saves the current diagram to a given path. Both take a preview ID that lets the agent return to a given diagram.

Where are working files stored?

In ~/.config/claude-mermaid/live. Live previews are kept there, so they survive a server restart.

What if puppeteer cannot be found?

Install the package globally with npm install -g claude-mermaid or reinstall the plugin in Claude Code. The README calls this error rare and environment-specific.

What does the green dot in the preview mean?

The page's WebSocket connection to the server: green means connected, red means reconnecting. The center button resets the diagram position.

Discussion

No questions or reviews yet.

MCP servers

MCP Mermaid

An MCP server that generates mermaid diagrams and charts with syntax validation and svg, png and file export

MCP serverExtended access649

Mermaid CLI

Mermaid CLI processes diagrams inside Markdown, creating SVG files and replacing diagram blocks with references to the images.

CLIExtended access5.2K

Draw.io MCP Server

Official

The official draw.io MCP server: an agent builds diagrams from XML or Mermaid and opens them in the draw.io editor

MCP serverExtended access5.8K

Excalidraw MCP Server

Excalidraw MCP Server, CLI & Agent Skill

A live Excalidraw canvas for the agent: creates, edits and exports diagrams over MCP or CLI, sees its own work via screenshots and saves .excalidraw files into

MCP serverExtended access2.6K

Next AI Draw.io

Next AI Draw.io is an MCP server and plugin where the agent draws draw.io diagrams on a live browser canvas that you can edit by hand

PluginExtended access36.9K

Smart Drawio

Smart Drawio Next

An MCP server and skill for editable draw.io diagrams: an agent generates XML from a prompt, validates references, repairs tags and applies themes

MCP serverExtended access366

Comparison with similar tools

Cards that share the main search query, and how they differ.

Tool	Official	Authentication	Repository stars	Main difference
Claude Mermaid (this card)	no	not required	221
MCP Mermaid	no	not required	649	renders diagrams to an image, while Claude Mermaid has a live browser preview
mermaid-skill	no		300	a skill with hints only, no server or preview

README in short

The README lists the server features, three install routes (plugin, npm, source), setup for Codex, Cursor, Cline and other clients, the parameters of the two tools, how live reload works and troubleshooting tips.

README badge

Original SKILL.md

---
name: mermaid-diagrams
description: Creating and refining Mermaid diagrams with live reload. Use when users want flowcharts, sequence diagrams, class diagrams, ER diagrams, state diagrams, or any other Mermaid visualization, and when writing, editing, restyling, or reviewing a Mermaid block in a Markdown file. Provides best practices for syntax, styling, and the iterative workflow using mermaid_preview and mermaid_save tools.
allowed-tools: mcp__mermaid__mermaid_preview, mcp__mermaid__mermaid_save, mcp__plugin_claude-mermaid_mermaid__mermaid_preview, mcp__plugin_claude-mermaid_mermaid__mermaid_save
---

# Mermaid Diagram Expert

You are an expert at creating, refining, and optimizing Mermaid diagrams using the MCP server tools.

## Core Workflow

1. **Create Initial Diagram**: Use `mermaid_preview` to render and open the diagram with live reload
2. **Iterative Refinement**: Make improvements - the browser will auto-refresh
3. **Save Final Version**: Use `mermaid_save` when satisfied

## Tool Usage

### mermaid_preview

Always use this when creating or updating diagrams:

- `diagram`: The Mermaid code
- `preview_id`: Descriptive kebab-case ID (e.g., `auth-flow`, `architecture`)
- `format`: Use `svg` for live reload (default)
- `theme`: `default`, `forest`, `dark`, or `neutral`
- `background`: `white`, `transparent`, or hex colors
- `size`, `scale`: Adjust for quality/size

**Key Points:**

- Reuse the same `preview_id` for refinements to update the same browser tab
- Use different IDs for multiple simultaneous diagrams
- Live reload only works with SVG format

### mermaid_save

Use after the diagram is finalized:

- `save_path`: Where to save (e.g., `./docs/diagram.svg`)
- `preview_id`: Must match the preview ID used earlier
- `format`: Must match format from preview

## Diagram Types

Report a problem