Mermaid MCP Server

A Mermaid diagram conversion server based on the Model Context Protocol (MCP), providing powerful diagram generation capabilities for AI clients

Project Introduction

Mermaid MCP Server is a professional Mermaid diagram conversion server based on the Model Context Protocol (MCP), providing powerful diagram generation capabilities for AI clients. This project converts Mermaid diagram code into image files in multiple formats (PNG, JPG, SVG, PDF), allowing users to easily generate high-quality diagrams in various AI clients that support the MCP protocol.

Core Features

• Multi-format Output: Supports multiple image formats including PNG, JPG, SVG, and PDF

• Theme Customization: Built-in four beautiful themes: default, dark, neutral, and forest

• Custom Options: Supports customization of parameters such as background color and image dimensions

• Syntax Validation: Provides real-time Mermaid syntax validation

• Example Resources: Built-in rich diagram type example code

• Error Handling: Comprehensive error handling mechanism with friendly error messages

• STDIO/SSE Dual Mode: Supports both STDIO and SSE communication modes

• uv Package Management: Uses the ultra-fast uv package manager

Related MCP server: mcp-mermaid-validator

Feature List

Technical Architecture

Communication Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            通信架构图                                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   ┌──────────────────┐       ┌─────────────────────────┐       ┌─────────────┐ │
│   │  AI 客户端         │ ◄────► │   Mermaid MCP Server    │ ◄────► │ Mermaid API │ │
│   │ (Cursor/Claude)   │       │   STDIO/SSE             │       │  mermaid.ink│ │
│   └──────────────────┘       └─────────────────────────┘       └─────────────┘ │
│           │                            │                              │        │
│           ▼                            ▼                              ▼        │
│   AI 对话界面                MCP 协议通信              图表渲染转换      │
│   生成图表请求                双向数据传输              返回图像数据     │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Installation Instructions

Environment Requirements

• Python 3.12+

• uv package manager (recommended)

Installing Dependencies

Method 1: Install with uv (recommended)

# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

# 安装依赖
uv sync

Method 2: Install with pip

pip install -r requirements.txt

Usage Instructions

Client Configuration

Cursor Configuration

Add the following configuration to the ~/.cursor/mcp.json file:

STDIO mode (recommended):

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "command": "uvx",
      "args": [
        "mermaid-mcp-server-png-pdf-jpg-svg"
      ]
    }
  }
}

SSE mode:

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "url": "http://127.0.0.1:8003/sse"
    }
  }
}

Cherry Studio Configuration

1. Open Cherry Studio

2. Go to Settings → MCP Servers → Add Server

3. Configure the parameters:

   • Name: mermaid-mcp-server-png-pdf-jpg-svg

   • Description: Mermaid diagram generation service

   • Type: STDIO

   • Command: uvx

   • Arguments: mermaid-mcp-server-png-pdf-jpg-svg

4. Click Save and enable

Claude Desktop Configuration

Add the following to the claude_desktop_config.json file:

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "command": "uvx",
      "args": [
        "mermaid-mcp-server-png-pdf-jpg-svg"
      ]
    }
  }
}

Continue.dev Configuration

Add the following to the config.json file:

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "command": "uvx",
      "args": [
        "mermaid-mcp-server-png-pdf-jpg-svg"
      ]
    }
  }
}

Starting the Service

STDIO mode (recommended for desktop clients)

uv run python main.py

SSE mode (for network connections)

uv run python main.py --sse

Configuration Instructions

Environment Variable Configuration

Available Tools

1. convert_mermaid_to_image

Converts Mermaid diagram code into image files in multiple formats

Parameters:

• mermaid_code (string): Mermaid diagram code

• output_format (string, optional): Output format, supports png, jpg, svg, pdf; default "png"

• theme (string, optional): Theme style, supports default, dark, neutral, forest; default "default"

• background_color (string, optional): Background color, hexadecimal code

• width (number, optional): Image width (pixels)

• height (number, optional): Image height (pixels)

Supported output formats: PNG, JPG, SVG, PDF

2. validate_mermaid_syntax

Validates the syntax correctness of Mermaid diagram code

Parameters:

• mermaid_code (string): Mermaid diagram code to validate

Return results:

• valid (boolean): Whether validation passed

• error_message (string): Error message (if validation fails)

3. get_supported_options

Gets the options supported by the converter

Return results:

• themes (array): List of supported themes

• formats (array): List of supported formats

Supported Diagram Types

• Flowchart: Used to represent processes and algorithms

• Sequence Diagram: Used to represent interactions between objects

• Gantt Chart: Used for project schedule management

• Pie Chart: Used to represent data proportions

• Git Graph: Used to represent Git commit history

• Mind Map: Used to represent knowledge structures

• Class Diagram: Used to represent class structures

Usage Examples

Flowchart Example

请使用 convert_mermaid_to_image 工具生成一个流程图：
flowchart TD
    A[开始] --> B{判断条件}
    B -->|是 | C[执行动作 1]
    B -->|否 | D[执行动作 2]
    C --> E[结束]
    D --> E

Sequence Diagram Example

请使用 convert_mermaid_to_image 工具生成一个时序图，使用深色主题：
sequenceDiagram
    participant 用户
    participant 系统
    participant 数据库

    用户->>系统：登录请求
    系统->>数据库：验证用户
    数据库-->>系统：返回结果
    系统-->>用户：登录成功

Syntax Validation Example

首先使用 validate_mermaid_syntax 验证语法，然后使用 convert_mermaid_to_image 生成图表

Resource Examples

Getting Diagram Examples

You can retrieve different types of diagram examples through the following resource URIs:

• mermaid://examples/flowchart - Flowchart example

• mermaid://examples/sequence - Sequence diagram example

• mermaid://examples/gantt - Gantt chart example

• mermaid://examples/pie - Pie chart example

• mermaid://examples/gitgraph - Git graph example

• mermaid://examples/mindmap - Mind map example

• mermaid://examples/class - Class diagram example

Project Structure

mermaid_mcp_server/
├── mermaid_mcp_server/       # 核心模块
│   ├── __init__.py
│   └── main.py             # 主程序入口
├── requirements.txt          # 依赖列表（pip）
├── pyproject.toml           # 项目配置（uv）
├── .env.example            # 环境变量示例
├── README.md               # 项目文档
└── .vscode/                # VSCode 配置
    └── settings.json

Development Guide

Local Development

# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

# 安装依赖
uv sync

# 配置环境变量
cp .env.example .env

# 启动服务（STDIO 模式）
uv run python main.py

# 启动服务（SSE 模式）
uv run python main.py --sse

Debug Mode

Enable verbose logging output:

export LOG_LEVEL=DEBUG
uv run python main.py

Frequently Asked Questions

A:

1. Check network connection and firewall settings

2. Confirm the mermaid.ink API is accessible

3. Check proxy settings

A:

1. Use the validate_mermaid_syntax tool to check syntax

2. Refer to the official Mermaid documentation

3. Use the code from the example resources

A:

1. Simplify the diagram content

2. Split it into multiple smaller diagrams

3. Adjust the image dimension parameters

A:

1. Install the uv package manager: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Or install the package globally with pip

3. Check the PATH environment variable

A:

1. Confirm the service has been started in SSE mode

2. Check whether port 8003 is occupied

3. Confirm the URL configuration is correct

A:

1. Increase the image dimension parameters

2. Choose an appropriate theme

3. Optimize the Mermaid code structure

A:

1. Check the network connection speed

2. Increase the REQUEST_TIMEOUT environment variable

3. Simplify the diagram complexity

A:

1. Confirm the theme name is spelled correctly

2. Check whether the theme is supported

3. Try using a different theme name

A:

1. Use the background_color parameter

2. The format is a hexadecimal color code (e.g., #FFFFFF)

3. Only supported for some output formats

Technical Community Group

Welcome to join the technical community group to share your usage experience and feedback:

Author Contact

• WeChat: laohaibao2025

• Email: 75271002@qq.com

Donations

If this project has been helpful to you, feel free to buy me a coffee ☕

WeChat Pay

Star History

If you like the project, feel free to give it a Star ⭐

License

MIT License

Changelog

v0.1.0 (Current version)

• ✅ Initial version released

• ✅ Supports multi-format output for PNG, JPG, SVG, PDF

• ✅ Integrates four theme styles (default, dark, neutral, forest)

• ✅ Provides syntax validation and example resource features

• ✅ Supports STDIO and SSE dual-mode communication

v0.0.3 (2025-07-21)

• ✅ Initial version released

• ✅ Supports multi-format diagram conversion

• ✅ Syntax validation feature

• ✅ Example resource feature

Contribution Guide

Welcome to submit Issues and Pull Requests to improve this project!

1. Fork this repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Commit your changes: git commit -m 'Add amazing feature'

4. Push to the branch: git push origin feature/amazing-feature

5. Submit a Pull Request

Notes

• Diagram generation may take a few seconds, please be patient

• Ensure the network connection is normal; the service depends on the mermaid.ink online API

• Generated image data is returned in base64 format

• Complex diagrams may require longer generation time

Enjoy creating beautiful diagrams with Mermaid! 🎨✨