📌Overview

Purpose: To provide a server that converts Mermaid diagrams written in markdown syntax into high-quality PNG images, enabling integration with AI assistants and various applications.

Overview: The Mermaid MCP Server utilizes the Model Context Protocol (MCP) to facilitate the conversion of Mermaid diagram code into visual representations. By leveraging Puppeteer for headless browser rendering, it ensures high-quality output and supports various customization options for themes and backgrounds.

Key Features:

Diagram Conversion: Efficiently transforms Mermaid diagram code into PNG images with high fidelity, making it suitable for various applications requiring visual documentation.
Customization Options: Offers multiple diagram themes (default, forest, dark, neutral) and customizable background colors to enhance the aesthetic appeal of the generated diagrams.
Seamless Integration: Implements the MCP protocol, allowing easy interaction with AI assistants and other applications, and includes flexibility for direct image returns or saving images to disk.

Mermaid MCP Server

A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images. This server allows AI assistants and other applications to generate visual diagrams from textual descriptions using the Mermaid markdown syntax.

Features

Converts Mermaid diagram code to PNG images
Supports multiple diagram themes (default, forest, dark, neutral)
Customizable background colors
Uses Puppeteer for high-quality headless browser rendering
Implements the MCP protocol for seamless integration with AI assistants
Flexible output options: return images directly or save to disk
Error handling with detailed error messages

How It Works

The server uses Puppeteer to launch a headless browser, render the Mermaid diagram to SVG, and capture a screenshot of the rendered diagram. The process:

Launch a headless browser instance
Create an HTML template with the Mermaid code
Load the Mermaid.js library
Render the diagram to SVG
Take a screenshot of the rendered SVG as PNG
Return the image directly or save it to disk

Build

npx tsc

Usage

Use with Claude desktop

"mcpServers": {
  "mermaid": {
    "command": "npx",
    "args": [
      "-y @peng-shawn/mermaid-mcp-server"
    ]
  }
}

Use with Cursor and Cline

env CONTENT_IMAGE_SUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server

You can find a list of mermaid diagrams under ./diagrams, created using Cursor agent with prompt: "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work"

Run with inspector

Run the server with inspector for testing and debugging:

npx @modelcontextprotocol/inspector node dist/index.js

The server will start and listen on stdio for MCP protocol messages.

Learn more about inspector here: https://modelcontextprotocol.io/docs/tools/inspector

Installing via Smithery

To install Mermaid Diagram Generator for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

Docker and Smithery Environments

When running in Docker containers (including via Smithery), you may need to handle Chrome dependencies:

The server attempts to use Puppeteer's bundled browser by default
If you encounter browser-related errors, two options:

Option 1: During Docker image build:
- Set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true when installing Puppeteer
- Install Chrome/Chromium in your Docker container
- Set PUPPETEER_EXECUTABLE_PATH at runtime to point to Chrome installation
Option 2: Use Puppeteer's bundled Chrome:
- Ensure your Docker container has necessary dependencies for Chrome
- No need to set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD
- The code will use the bundled browser automatically

For Smithery users, the latest version should work without additional configuration.

API

The server exposes a single tool:

generate: Converts Mermaid diagram code to a PNG image
- Parameters:
  - code: Mermaid diagram code to render
  - theme: (optional) Theme for the diagram. Options: "default", "forest", "dark", "neutral"
  - backgroundColor: (optional) Background color for the diagram, e.g. 'white', 'transparent', '#F0F0F0'
  - name: Name for the generated file (required when CONTENT_IMAGE_SUPPORTED=false)
  - folder: Absolute path to save the image to (required when CONTENT_IMAGE_SUPPORTED=false)

Behavior depends on the CONTENT_IMAGE_SUPPORTED environment variable:

true (default): returns the image directly in the response
false: saves the image to specified folder and returns the file path

Environment Variables

CONTENT_IMAGE_SUPPORTED: Controls image output method
- true (default): images are returned directly
- false: images saved to disk; requires name and folder parameters

Examples

Basic Usage

// Generate a flowchart with default settings
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

With Theme and Background Color

// Generate a sequence diagram with forest theme and light gray background
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

Saving to Disk (when CONTENT_IMAGE_SUPPORTED=false)

// Generate a class diagram and save it to disk
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

FAQ

Doesn't Claude desktop already support mermaid via canvas?

Yes, but it doesn't support the theme and backgroundColor options. A dedicated server makes it easier to create mermaid diagrams with different MCP clients.

Why specify CONTENT_IMAGE_SUPPORTED=false when using with Cursor?

Cursor doesn't support inline images in responses yet.

Publishing

This project uses GitHub Actions to automate publishing to npm.

Method 1: Using the Release Script (Recommended)

Commit and push all changes

Run the release script with a specific version or semantic increment:

# Specific version
npm run release 0.1.4

# Semantic increments
npm run release patch
npm run release minor
npm run release major

The script will:
- Validate version format
- Check main branch
- Warn about version mismatches
- Update all version references
- Create a commit and push a git tag
- GitHub workflow builds and publishes to npm

Method 2: Manual Process

Commit changes
Create and push a version tag:
```
git tag v0.1.4
git push origin v0.1.4
```
GitHub workflow will build and publish automatically

Note on NPM_TOKEN

You need to set up the NPM_TOKEN secret in your GitHub repository settings:

Generate an npm access token with publish permissions
Go to GitHub repository → Settings → Secrets and variables → Actions
Create a new secret named NPM_TOKEN with your token

License

MIT