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

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, 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:

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:

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 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true when installing Puppeteer
   • Install Chrome/Chromium in your Docker container
   • Set PUPPETEER_EXECUTABLE_PATH 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 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 or SVG file
  • Parameters:
    • code: The 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'
    • outputFormat: (optional) Output format for the diagram. Options: "png", "svg" (defaults to "png")
    • name: Name for the generated file (required when CONTENT_IMAGE_SUPPORTED=false)
    • folder: Absolute path to save the image/SVG to (required when CONTENT_IMAGE_SUPPORTED=false)

The behavior of the generate tool depends on the CONTENT_IMAGE_SUPPORTED environment variable:

• When CONTENT_IMAGE_SUPPORTED=true (default): The tool retur

... View full README on GitHub