peng-shawn/mermaid-mcp-server

A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images or SVG files. 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 or SVG files
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/SVG 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 optionally capture a screenshot of the rendered diagram. The process involves:
1. Launching a headless browser instance
2. Creating an HTML template with the Mermaid code
3. Loading the Mermaid.js library
4. Rendering the diagram to SVG
5. Either saving the SVG directly or taking a screenshot as PNG
6. Either returning the image/SVG directly or saving it to disk
## Requirements
Node.js 22.12.0 or later
> Security notice: versions before 0.3.0 depend on Puppeteer and Mermaid releases with known vulnerabilities. Please upgrade to 0.3.0 or later. The configurations below use @latest so npx picks up new releases.
## Build
bash
npx tsc
## Usage
### Use with Claude desktop
json
"mcpServers": {
"mermaid": {
"command": "npx",
"args": ["-y", "@peng-shawn/mermaid-mcp-server@latest"]
### Use with Cursor and Cline
bash
env CONTENTIMAGESUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server@latest
You can find a list of mermaid diagrams under ./diagrams, they are 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:
bash
npx @modelcontextprotocol/inspector node dist/index.js
The server will start and listen on stdio for MCP protocol messages.
Learn more about inspector here.
### Installing via Smithery
To install Mermaid Diagram Generator for Claude Desktop automatically via Smithery:
bash
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:
1. The server now attempts to use Puppeteer's bundled browser by default
2. If you encounter browser-related errors, you have two options:
Option 1: During Docker image build:
Set PUPPETEERSKIPCHROMIUMDOWNLOAD=true when installing Puppeteer
Install Chrome/Chromium in your Docker container
Set PUPPETEEREXECUTABLEPATH at runtime to point to the Chrome installation
Option 2: Use Puppeteer's bundled Chrome:
Ensure your Docker container has the necessary dependencies for Chrome
No need to set PUPPETEERSKIPCHROMIUMDOWNLOAD
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 or SVG file