Content
# 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](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](https://docs.astral.sh/uv/getting-started/installation/) 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:
```bash
# 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.
```bash
# 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
```bash
# Binary typically installed at:
~/.local/bin/mcp-mermaid-image-gen
# Verify exact location:
which mcp-mermaid-image-gen
```
### Linux
```bash
# Binary typically installed at:
~/.local/bin/mcp-mermaid-image-gen
# Verify exact location:
which mcp-mermaid-image-gen
```
### Windows
```powershell
# 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)
```json
{
"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)
```json
{
"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:
```bash
# 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
```json
{
"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:
```bash
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:
```bash
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
```bash
# 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)
```bash
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:
```bash
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](LICENSE) file for details.
