How to Use Claude × Mermaid | From Diagram Generation to MCP Live Preview

What Is Mermaid — A Syntax for Drawing Diagrams in Text

Mermaid is an open-source diagramming tool that renders diagrams from declarative text written inside Markdown code blocks. For example, the following three lines are all you need to create a flowchart:

graph TD
  A[要件定義] --> B[実装]
  B --> C[レビュー]

It supports a wide variety of diagram types — flowcharts, sequence diagrams, state diagrams, class diagrams, ER diagrams, Gantt charts, and more — all within a single syntax system. Since GitHub, Notion, and many technical documentation tools support rendering out of the box, Mermaid is becoming the de facto standard for engineers' design documents, READMEs, and specification sheets.

Why Claude Is a Perfect Match for Mermaid

Because Claude has been trained on a large volume of GitHub repositories and technical documents, it can not only "write" Mermaid syntax correctly but also "understand it semantically" (as noted in MindStudio's article). This characteristic works in two directions:

1. Generation: Simply ask in natural language — "Turn this process flow into a sequence diagram" — and Claude outputs correct Mermaid code.
2. Comprehension: Embed a Mermaid diagram in your instructions, and Claude grasps the process with accuracy equal to or greater than a prose explanation.

In other words, for Claude, Mermaid serves simultaneously as an "output format" and an "input format."

Basics of Creating Mermaid Diagrams in claude.ai

In the browser version of claude.ai, the Artifacts feature lets you preview generated Mermaid diagrams on the spot. Here are the steps:

1. Ask in chat: "Illustrate the flow of ○○ as a Mermaid flowchart."
2. The generated diagram is rendered in the Artifacts panel.
3. Refine it through conversation: "Add more branches," "Use a vertical layout," etc.
4. Once finished, copy the Mermaid code and paste it into your README or design document.

The key difference from image generation tools is that you receive the diagram as "text code" rather than an image — meaning you can edit it yourself later and manage diffs in Git.

Live Preview with the claude-mermaid MCP Server

If you want to use Mermaid seriously in Claude Code (the terminal version), installing veelenga/claude-mermaid (MIT License) is recommended. This is an MCP server that adds Mermaid rendering capabilities to Claude Code, automatically displaying generated diagrams in your browser and live-reloading them via WebSocket each time you make a change.

Key features include:

• Automatic browser refresh every time a diagram is modified (live reload)
• Save in three formats: SVG / PNG / PDF
• Theme switching (default / forest / dark / neutral)
• Interactive preview with pan, zoom, and reset
• Simultaneously work on multiple diagrams using separate preview_id values

Installation Steps for claude-mermaid

The official README describes three installation methods. The easiest is via plugin.

Step 1: Install the Plugin

Run the following two commands inside a Claude Code session:

/plugin marketplace add veelenga/claude-mermaid
/plugin install claude-mermaid@claude-mermaid

You can also install it globally via npm (npm install -g claude-mermaid) or clone the repository and build from source.

Step 2: Request Diagram Generation and Preview

After installation, simply tell Claude Code: "Illustrate the dependencies of this module in Mermaid and preview it." The mermaid_preview tool exposed by the MCP server will be called and the diagram will appear in your browser. You can also specify parameters such as width, height, scale, background, and theme.

Step 3: Save the Finished Diagram

When you are happy with the result, say "Save it as SVG" and the mermaid_save tool will output the file. Specifying PNG or PDF lets you receive the diagram in a format ready for pasting into documents.

Advanced Use: Compressing Context with Mermaid Diagrams

Mermaid is also attracting attention beyond diagram creation — as a tool for making instructions to Claude more efficient. According to MindStudio's research article, describing a complex workflow with conditional branching in prose requires 800–1,500 tokens, whereas a Mermaid diagram can convey equivalent information in 150–350 tokens — roughly a 3–6× improvement in token efficiency.

When writing processes in custom instruction files for Claude Code, embedding a single flowchart instead of lengthy prose reduces context consumption and also cuts down on ambiguity. Here are guidelines for which diagram type to use for each kind of process:

• Procedures with conditional branching or decision gates → Flowchart
• Interactions between multiple systems → Sequence diagram
• Error handling or state transitions → State diagram
• Relationships in data structures → Class diagram / ER diagram

The key tip here is to "keep node labels short and write details outside the diagram." Cramming too much information into the diagram actually hurts both readability and token efficiency.

Common Pitfalls and How to Handle Them

Here are three problems you are likely to encounter when you start using Mermaid:

1. Diagram fails to render due to syntax errors: Mermaid has restrictions on the characters allowed in node names. For Japanese labels, wrap them in square brackets like A[Japanese text], and for labels containing parentheses or quotes, wrap the entire label in double quotes like A["text (note)"] to avoid errors. If you encounter an error, just paste the error message directly to Claude — in most cases it will self-correct.
2. A huge diagram becomes unreadable: Rather than cramming everything into a single diagram, it is more practical to ask Claude to split it into an "overview diagram" plus "detailed diagrams for each part." With claude-mermaid, you can use separate preview_id values to preview multiple diagrams in parallel.
3. Browser preview does not update: The live reload feature of claude-mermaid requires an active WebSocket connection. If you accidentally close the browser tab, simply request a preview again and it will open in a new tab.

Summary — Incorporate Mermaid into Your Design Documentation

The Claude × Mermaid combination is a practical workflow for "turning the structures in your head into documentation at maximum speed." Start by casually creating diagrams with Artifacts in claude.ai, set up a live preview environment with the claude-mermaid MCP server if you use Claude Code, and then, once comfortable, advance to embedding diagrams in instruction files for context compression — a gradual adoption path is recommended.

Diagrams managed as text can be reviewed like code, have their diffs tracked, and can be read and written by AI. As your first step toward shifting design documentation from "drawing" to "writing," try having Claude illustrate one familiar process flow for you.

Sources:

• veelenga/claude-mermaid - GitHub
• Mermaid Official Site
• How to Use Mermaid Diagrams in Claude Code Skills to Compress Context - MindStudio