Skip to main content
Glama
deenesjakoruzh
veelenga

claude-mermaid

by veelenga
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

Claude Mermaid MCP Server

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.

Demo

✨ 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

Related MCP server: mcp-mermaid-validator

Architecture

Architecture Diagram

User Workflow Diagram

Dependencies Diagram

🚀 Quick Start

1. Install

Plugin Install (Recommended)

In Claude Code, add the marketplace and install the plugin:

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

Then restart Claude Code to activate the plugin.

From npm:

npm install -g claude-mermaid

From source:

git clone https://github.com/veelenga/claude-mermaid.git
cd claude-mermaid
npm install && npm run build && npm install -g .

2. Verify Installation

Plugin install: The MCP server is configured automatically. Just verify:

/mcp

You should see mermaid in the MCP server list.

npm install: Configure the MCP server manually:

claude mcp add --scope user mermaid claude-mermaid

Then verify:

claude mcp list

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:

Add to your Codex MCP settings file (~/.codex/mcp_settings.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Or configure via Codex CLI:

codex mcp add mermaid claude-mermaid

Add to your Cursor MCP config file (.cursor/mcp.json or settings):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

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

If using the Cline extension for VSCode:

  1. Open VSCode settings (Cmd/Ctrl + ,)

  2. Search for "Cline MCP"

  3. Add to MCP Settings JSON:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Add to Windsurf's MCP configuration file:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Configuration location varies by platform:

  • macOS: ~/Library/Application Support/Windsurf/mcp.json

  • Linux: ~/.config/windsurf/mcp.json

  • Windows: %APPDATA%\Windsurf\mcp.json

Add to Gemini CLI's MCP configuration file (~/.gemini/mcp.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Or use the Gemini CLI to configure:

gemini config mcp add mermaid --command claude-mermaid

For any MCP-compatible client, use the standard configuration:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

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

"Create a Mermaid diagram showing the user authentication flow"
"Draw a sequence diagram for the payment process"
"Generate a flowchart for the deployment pipeline"

Advanced Examples

With custom formatting:

"Create a dark theme architecture diagram with transparent background"
"Generate a forest theme flowchart and save to ./docs/flow.svg"

With specific output format:

"Create an ER diagram and save as PDF to ./docs/schema.pdf"
"Save the flowchart as PNG to ./docs/flow.png"

Note: Browser always shows SVG for live preview, while saving to your chosen format.

Iterative refinement:

"Create a class diagram for the User module"
// Browser opens with live preview
"Add the Address and Order classes with relationships"
// Diagram updates automatically in browser!

Complete Example

"Create a flowchart and save to ./docs/auth-flow.svg:

graph LR
    A[User Login] --> B{Valid Credentials?}
    B -->|Yes| C[Access Granted]
    B -->|No| D[Access Denied]
    C --> E[Dashboard]
    D --> F[Try Again]

    style A fill:#e1f5ff
    style C fill:#d4edda
    style D fill:#f8d7da
"

The diagram will be saved to ./docs/auth-flow.svg and opened in your browser with live reload enabled.

🔧 Tools and Parameters

There are two tools exposed by the MCP server:

  1. mermaid_preview — render and open a live preview

  • diagram (string, required) — Mermaid diagram code

  • preview_id (string, required) — Identifier for this preview session. Use different IDs for multiple concurrent diagrams (e.g., architecture, flow).

  • format (string, default svg) — One of svg, png, pdf. Live preview is available only for svg.

  • theme (string, default default) — One of default, forest, dark, neutral.

  • background (string, default white) — Background color. Examples: transparent, white, #F0F0F0.

  • width (number, default 800) — Diagram width in pixels.

  • height (number, default 600) — Diagram height in pixels.

  • scale (number, default 2) — Scale factor for higher quality output.

  1. mermaid_save — save the current live diagram to a path

  • save_path (string, required) — Destination path (e.g., ./docs/diagram.svg).

  • preview_id (string, required) — Must match the preview_id used in mermaid_preview.

  • format (string, default svg) — One of svg, png, pdf. If the live working file for this format doesn’t exist yet, it is rendered on demand before saving.

🎯 How Live Reload Works

  1. First render: Opens diagram in browser at http://localhost:3737/{preview_id}

  2. Make changes: Edit the diagram through Claude Code

  3. Auto-refresh: Browser detects changes via WebSocket and reloads

  4. Status indicator: Green dot = connected, Red dot = reconnecting

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

Live Preview Controls

  • Pan: Click and drag the diagram to move it around

  • Zoom: Use browser zoom (Ctrl/Cmd + +/- or pinch-to-zoom on trackpad)

  • Reset Position: Click the ⊙ button in the status bar to recenter the diagram

  • Export: Click the ⬇ button to download as SVG or PNG

Notes

  • Live preview is available for svg format only; PNG/PDF are rendered without live reload.

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

🖥️ Standalone server

You can start the preview server without an AI agent using the --serve flag:

claude-mermaid --serve

This opens the diagram gallery in your browser with all previously rendered diagrams. Useful for browsing and exporting diagrams outside of a Claude Code session.

🛠️ Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

# Start the MCP server directly
npm start

📝 Troubleshooting

Error: Cannot find package 'puppeteer':

This is a rare environment-specific issue. Try these solutions:

  1. Install claude-mermaid globally:

    npm install -g claude-mermaid

  2. Reinstall the plugin in Claude Code:

    /plugin uninstall claude-mermaid
/plugin install claude-mermaid@claude-mermaid

Server not connecting:

# Check if server is installed
claude-mermaid -v

# Reinstall if needed
npm install -g claude-mermaid

# Verify MCP configuration
claude mcp list

Permission denied error:

# Make sure the binary is executable
chmod +x $(which claude-mermaid)

Port already in use:

  • The server uses ports 3737-3747

  • It will automatically find an available port

  • Check if another process is using these ports: lsof -i :3737-3747

Diagrams not rendering or live reload not working:

The server logs to ~/.config/claude-mermaid/logs/:

  • mcp.log - Tool requests and diagram rendering

  • web.log - HTTP/WebSocket connections and live reload

Enable debug logging in your MCP config:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid",
      "env": {
        "CLAUDE_MERMAID_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Then check the logs:

# View MCP operations
tail -f ~/.config/claude-mermaid/logs/mcp.log

# View WebSocket connections
tail -f ~/.config/claude-mermaid/logs/web.log

Available log levels: DEBUG, INFO (default), WARN, ERROR, OFF

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT - see LICENSE file for details

🔗 Links

👀 See Also

If you like this project, you might also be interested in

  • preview-skills — preview skills for visualizing files in the browser (markdown, csv, json, mermaid and more)

Hosted deployment

A hosted deployment is available on Fronteir AI.

Available Tools

2 tools
mermaid_previewA

Render a Mermaid diagram and open it in browser with live reload. Takes Mermaid diagram code as input and generates a live preview. Supports themes (default, forest, dark, neutral), custom backgrounds, dimensions, and quality scaling. The diagram will auto-refresh when updated. Use mermaid_save to save to disk. IMPORTANT: Automatically use this tool whenever you create a Mermaid diagram for the user. NOTE: Sequence diagrams do not support style directives - avoid using 'style' statements in sequenceDiagram.

ParametersJSON Schema
NameRequiredDescriptionDefault
diagramYesThe Mermaid diagram code to render
preview_idYesID for this preview session. Use different IDs for multiple diagrams (e.g., 'architecture', 'flow', 'sequence').
formatNoOutput format (default: svg)svg
themeNoTheme of the chart (default: default)default
backgroundNoBackground color for pngs/svgs. Example: transparent, red, '#F0F0F0' (default: white)white
widthNoDiagram width in pixels (default: 800)
heightNoDiagram height in pixels (default: 600)
scaleNoScale factor for higher quality output (default: 2)

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool opens a browser with live reload, auto-refreshes when updated, supports themes and customizations, and has limitations for sequence diagrams. However, it doesn't mention potential side effects like browser pop-ups or network requirements, leaving some behavioral aspects implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose. Every sentence adds value: the first states the main action, the second details features, the third covers auto-refresh and sibling tool, and the last two provide critical usage notes. However, the structure could be slightly more streamlined by combining related points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, live preview functionality) and lack of annotations or output schema, the description does a good job covering essential context: purpose, usage rules, key features, and limitations. It adequately guides an agent on how and when to use the tool, though it doesn't detail the preview interface or error handling, which are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description adds minimal parameter-specific information beyond the schema, mentioning themes and custom backgrounds generically. This meets the baseline of 3 since the schema does the heavy lifting, but the description doesn't significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Render a Mermaid diagram and open it in browser with live reload') and distinguishes it from its sibling tool ('Use mermaid_save to save to disk'). It explicitly mentions the resource (Mermaid diagram) and the verb (render/preview), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool ('Automatically use this tool whenever you create a Mermaid diagram for the user') and when not to use it for saving ('Use mermaid_save to save to disk'). It also includes a specific exclusion for sequence diagrams ('Sequence diagrams do not support style directives - avoid using 'style' statements in sequenceDiagram'), offering clear alternatives and limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mermaid_saveA

Save the current live Mermaid diagram to a file path. This copies the already-rendered diagram from the live preview to the specified location. Use this after tuning your diagram with mermaid_preview.

ParametersJSON Schema
NameRequiredDescriptionDefault
save_pathYesPath to save the diagram file (e.g., './docs/diagram.svg')
preview_idYesID of the preview to save. Must match the preview_id used in mermaid_preview.
formatNoOutput format (default: svg). Must match the format used in mermaid_preview.svg

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool copies an already-rendered diagram from the live preview, which is useful context beyond the input schema. However, it doesn't mention potential side effects (e.g., file overwriting), error conditions, or what happens if the preview_id doesn't exist, leaving some behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by a clear usage guideline. Both sentences earn their place by providing essential context and guidance without any redundant or verbose language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 parameters, no annotations, no output schema), the description is reasonably complete. It explains the tool's purpose, usage timing, and relationship to the sibling tool. However, it lacks details on output behavior (e.g., success/failure responses) and potential errors, which would be helpful given the absence of annotations and output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema by mentioning the diagram is 'already-rendered' and comes from the 'live preview', which provides context but no additional parameter-specific details. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Save'), resource ('current live Mermaid diagram'), and destination ('to a file path'), distinguishing it from the sibling tool mermaid_preview by specifying it operates on the already-rendered diagram from the preview. This provides explicit verb+resource+scope differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('Use this after tuning your diagram with mermaid_preview'), providing clear sequencing guidance and linking it directly to the sibling tool. It also implies when not to use it (e.g., before previewing), though it doesn't name explicit alternatives beyond the sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

The two tools have perfectly distinct purposes: mermaid_preview renders and displays a diagram in a browser with live updates, while mermaid_save saves the rendered diagram to disk. There is no overlap or ambiguity between them, as each handles a separate stage of the diagram workflow.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with the 'mermaid_' prefix: mermaid_preview and mermaid_save. The naming is clear, predictable, and uniform throughout the set, making it easy for an agent to understand their functions.

Tool Count3/5

With only two tools, the set feels thin for a Mermaid diagram server, as it lacks operations like editing, exporting to different formats, or managing themes programmatically. However, it covers the core preview-and-save workflow, so it's borderline but not severely mismatched.

Completeness3/5

The tools provide basic functionality for previewing and saving diagrams, but there are notable gaps: no tool for creating or editing diagrams from scratch, no support for different output formats (e.g., PNG, SVG), and no way to manage themes or settings beyond the preview. This limits the server's utility for full diagram lifecycle management.

Maintenance

ActivityActive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/veelenga/claude-mermaid'

If you have feedback or need assistance with the MCP directory API, please join our Discord server