MCP Mermaid Image Gen

An MCP server that generates diagrams from Mermaid code in multiple formats (primarily PNG and PDF, with SVG also available). This server enables AI assistants and other MCP clients to create diagrams using the Mermaid diagram syntax, with support for multiple themes, formats, and customizable backgrounds.

Overview

This MCP server wraps the Mermaid CLI (@mermaid-js/mermaid-cli) to provide diagram generation capabilities through the Model Context Protocol (MCP). It offers two operation modes:

1. File-based: Save diagrams to disk and return the file path
2. Stream-based: Return the diagram directly as base64-encoded data

Both modes work with either STDIO or SSE transport, but the stream-based mode requires an MCP client capable of handling image data.

The server is designed to be used by AI coding assistants and other tools that support the MCP protocol, allowing them to generate diagrams without needing direct access to the Mermaid CLI.

📚 For AI Assistants: See AI_SETUP_GUIDE.md for a structured guide to help users with installation.

Features

• Generate diagrams from Mermaid syntax (flowcharts, sequence diagrams, class diagrams, etc.)
• Multiple output formats:
  • PNG: Raster graphics, recommended for general use and broad compatibility.
  • PDF: Document format, perfect for print and formal documentation.
  • SVG: Vector graphics, available for web and scalable diagrams where specifically needed.
• Support for multiple themes (default, neutral, dark, forest, base)
• Customizable background colors (hex codes or named colors)
• Two operation modes (both available in STDIO and SSE transport):
  • File-based: Save diagrams to disk and return the path
  • Stream-based: Return base64-encoded diagram data (requires MCP client with image support)
• Comprehensive error handling and validation
• Detailed logging with configurable levels

Prerequisites

Required

• UV Package Manager: Install using the official installer or via curl -LsSf https://astral.sh/uv/install.sh | sh on Unix-like systems.
• Operating Systems: Linux, macOS, Windows are supported.

Auto-Managed (Optional Manual Install)

• Node.js: Version 14 or higher. The server will attempt to use system Node.js if available.
• Mermaid CLI: The server will automatically install a local copy if not found in PATH. For manual system-wide installation: npm install -g @mermaid-js/mermaid-cli

🚀 Auto-Installation Feature: If Node.js is available but the Mermaid CLI (mmdc) is not found, the server will automatically install it to a user-specific directory (~/.local/share/mcp_mermaid_image_gen/ on Linux/macOS or %LOCALAPPDATA%\mcp_mermaid_image_gen\ on Windows). This happens transparently on first use.

Installation Methods

Primary Method: UV Tool Install (Recommended)

The most reliable way to install this MCP server is using uv tool install. This creates an isolated environment and installs the server with all its dependencies:

# Install the MCP server as a UV tool
uv tool install mcp-mermaid-image-gen

# Verify installation and find the binary location
uv tool list | grep mcp-mermaid-image-gen
# Note the installation path shown in the output

Fallback Method: UVX (Direct Execution)

⚠️ Warning: This method may encounter dependency conflicts if other tools in your environment use incompatible versions of shared dependencies.

# Run directly with uvx (downloads and caches on first run)
uvx mcp-mermaid-image-gen

Platform-Specific Binary Locations

After installation with uv tool install, find your binary location:

macOS

# Binary typically installed at:
~/.local/bin/mcp-mermaid-image-gen

# Verify exact location:
which mcp-mermaid-image-gen

Linux

# Binary typically installed at:
~/.local/bin/mcp-mermaid-image-gen

# Verify exact location:
which mcp-mermaid-image-gen

Windows

# Binary typically installed at:
%USERPROFILE%\.local\bin\mcp-mermaid-image-gen.exe

# Verify exact location:
where mcp-mermaid-image-gen

Configuring Your MCP Client

Claude Desktop Configuration

Configure Claude Desktop by editing the claude_desktop_config.json file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using UV Tool (After Installation)

{
  "mcpServers": {
    "mermaid_image_generator": {
      "command": "/absolute/path/to/mcp-mermaid-image-gen"
    }
  }
}

Replace /absolute/path/to/mcp-mermaid-image-gen with the actual path from the verification step above.

Option 2: Using UVX (Direct Execution)

{
  "mcpServers": {
    "mermaid_image_generator": {
      "command": "uvx",
      "args": [
        "mcp-mermaid-image-gen"
      ]
    }
  }
}

Other MCP Clients

Adapt the configuration to your client's format, using either:

• The absolute path to the installed binary (Option 1)
• The uvx command with mcp-mermaid-image-gen as an argument (Option 2)

Development Installation

For contributing to the server or running a modified version:

# Clone the repository
git clone https://github.com/yourusername/mcp_mermaid_image_gen.git
cd mcp_mermaid_image_gen

# Create and activate a virtual environment using UV
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install -e .

# Find the development binary
which mcp-mermaid-image-gen

Development Configuration Example

{
  "mcpServers": {
    "mermaid_image_generator_dev": {
      "command": "/path/to/your/project/.venv/bin/mcp-mermaid-image-gen"
    }
  }
}

Troubleshooting

Dependency Conflicts

If you encounter dependency conflicts when using uvx:

1. Use uv tool install instead for a fully isolated environment
2. Check for conflicting packages: uv tool list
3. If issues persist, uninstall and reinstall:

   uv tool uninstall mcp-mermaid-image-gen
   uv tool install mcp-mermaid-image-gen
   

Binary Not Found

If the MCP client can't find the binary:

1. Verify installation: uv tool list | grep mcp-mermaid-image-gen
2. Check PATH: Ensure ~/.local/bin is in your PATH
3. Use the absolute path in your client configuration

Testing with MCP Inspector

The MCP SDK includes a development console (MCP Inspector) that allows you to test the server interactively. After installation, run:

mcp dev mcp_mermaid_image_gen/server/app.py

This will:

1. Start the MCP Inspector web interface
2. Allow testing via both STDIO and SSE transport modes
3. Provide a UI for calling the server's tools
4. Display returned images directly in the browser
5. Show detailed logs and debugging information

The Inspector is particularly useful for:

• Testing different diagram types
• Trying out various formats (PNG, PDF, and SVG)
• Experimenting with themes and colors
• Debugging issues with Mermaid syntax
• Verifying both file and stream-based operation modes

Available Tools

generate_mermaid_diagram_file

Generates a Mermaid diagram and saves it to a local file.

Parameters:

• code (str): Mermaid diagram syntax
• folder (str): Output directory path
• name (str): Output filename (extension can determine format)
• theme (str, optional): Theme name (default, neutral, dark, forest, base)
• backgroundColor (str, optional): Background color (hex or named color)
• format (str, optional): Output format. Recommended: "png". Also supports "pdf". "svg" is available but not recommended for general use. If not specified:
  1. Inferred from filename extension (e.g., "diagram.png" -> png).
  2. Defaults to "png" if no valid extension or format is provided.

Returns: Path to the generated file

Format Selection Priority:

1. Explicit format parameter if provided
2. File extension in name parameter if valid
3. Defaults to PNG if neither is specified

generate_mermaid_diagram_stream

Generates a Mermaid diagram and returns it directly as base64-encoded data. Requires an MCP client that supports handling image data (like the MCP Inspector).

Parameters:

• code (str): Mermaid diagram syntax
• theme (str, optional): Theme name (default, neutral, dark, forest, base)
• backgroundColor (str, optional): Background color (hex or named color)
• format (str, optional): Output format. Recommended: "png". Also supports "pdf". "svg" is available but not recommended. Defaults to "png" if not specified.

Returns: Base64-encoded diagram data with appropriate MIME type:

• PNG: image/png
• PDF: application/pdf
• SVG: image/svg+xml (available if explicitly requested)

Transport Modes

Both STDIO and SSE transport modes support all server functionality. The choice between them depends on your use case:

STDIO Mode (Default)

• Synchronous operation
• Simple command-line integration
• Works with all tools and operation modes
• Ideal for scripts and command-line tools
• Example client: MCP Inspector, Cursor

SSE Mode

• Asynchronous operation
• HTTP-based communication
• Works with all tools and operation modes
• Ideal for web applications and services
• Example client: MCP Inspector, web applications

Client Compatibility

The server supports any MCP client, but some features require specific client capabilities:

1. File-based generation (generate_mermaid_diagram_file):

   • Requires client to have file system access
   • Works with all MCP clients
   • Client must be able to read the returned file path

2. Stream-based generation (generate_mermaid_diagram_stream):

   • Requires client capable of handling base64-encoded image data
   • Works with MCP Inspector and other image-capable clients
   • No file system access needed

The MCP Inspector (included with the MCP SDK) supports all features in both transport modes.

Usage

The server provides two entry points:

1. mcp_mermaid_image_gen-server: The MCP server

   # Run with stdio transport (default)
   mcp_mermaid_image_gen-server
   
   # Run with SSE transport
   mcp_mermaid_image_gen-server --transport sse --port 3001
   

2. mcp_mermaid_image_gen-client: Test client (for development)

   mcp_mermaid_image_gen-client "your mermaid code here"
   

Logging

The server logs all activity to both stderr and a rotating log file. Log files are stored in OS-specific locations:

• macOS: ~/Library/Logs/mcp-servers/mcp_mermaid_image_gen.log
• Linux:
  • Root user: /var/log/mcp-servers/mcp_mermaid_image_gen.log
  • Non-root: ~/.local/state/mcp-servers/logs/mcp_mermaid_image_gen.log
• Windows: %USERPROFILE%\AppData\Local\mcp-servers\logs\mcp_mermaid_image_gen.log

Log files are automatically rotated when they reach 10MB, with up to 5 backup files kept.

Configure logging level with the LOG_LEVEL environment variable:

LOG_LEVEL=DEBUG mcp_mermaid_image_gen-server

Valid log levels: DEBUG, INFO (default), WARNING, ERROR, CRITICAL

Author

Tim Kitchens (timkitch@codingthefuture.ai)

License

This project is licensed under the MIT License. See the LICENSE file for details.