Skip to main content
Glama
Mermaid MCP Server

Mermaid MCP Server

by wwwzhouhui

Mermaid MCP Server

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

License Python MCP UV


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

Feature Name

Description

Tech Stack

Status

Diagram Conversion

Mermaid code to image

mermaid.ink API

✅ Stable

Multi-format Output

PNG/JPG/SVG/PDF

requests + base64

✅ Stable

Theme Customization

4 built-in themes

mermaid.ink

✅ Stable

Syntax Validation

Real-time syntax checking

mermaid-cli

✅ Stable

Example Resources

Rich diagram examples

Static resources

✅ Stable

Error Handling

Comprehensive error messages

Python exception handling

✅ Stable

MCP Protocol

Model Context Protocol

mcp[cli]

✅ Stable

SSE Mode

Server-Sent Events

FastAPI + Uvicorn

✅ Stable


Technical Architecture

Technology

Version

Purpose

Python

3.12+

Primary development language

MCP

1.9+

Model Context Protocol

FastAPI

0.104+

Web framework (SSE mode)

Uvicorn

0.24+

ASGI server

requests

2.31+

HTTP client

uv

latest

Python package manager

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

Cherry Studio configuration example

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

uv run python main.py

SSE mode (for network connections)

uv run python main.py --sse

Configuration Instructions

Environment Variable Configuration

Variable Name

Description

Default Value

HOST

Server address

0.0.0.0

PORT

Server port

8003

LOG_LEVEL

Log level

INFO

MERMAID_API_BASE_URL

Mermaid API address

https://mermaid.ink

REQUEST_TIMEOUT

Request timeout (seconds)

30

DEBUG

Debug mode

false

DEVELOPMENT_MODE

Development mode

false


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:

Technical community group


Author Contact

WeChat QR code


Donations

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

WeChat Pay

WeChat Pay


Star History

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

Star History Chart


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! 🎨✨

Available Tools

3 tools
convert_mermaid_to_imageA
将 Mermaid 图表代码转换为多种格式的图像(PNG、JPG、PDF、SVG)。

参数:
    mermaid_code: 要转换的 Mermaid 图表语法代码
    output_format: 输出格式 - png、jpg、svg 或 pdf(默认:png)
    theme: 视觉主题 - default、dark、neutral 或 forest(默认:default)
    background_color: 背景颜色,十六进制代码(如 FF0000)或带 ! 前缀的命名颜色(如 !white)
    width: 图像宽度(像素,可选)
    height: 图像高度(像素,可选)

返回:
    包含转换后图像数据和元数据的字典

Inputs: mermaid_code (required), output_format, theme, background_color, +2 more. Returns: result

get_supported_optionsA
获取转换器支持的选项,如图表主题和输出格式。

返回:
    一个包含支持的主题和格式列表的字典。

Inputs: no named parameters. Returns: result

validate_mermaid_syntaxB
通过尝试简单转换来验证 Mermaid 图表语法。

参数:
    mermaid_code: 要验证的 Mermaid 图表语法代码

返回:
    包含验证结果的字典

Inputs: mermaid_code (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: convert_mermaid_to_image handles the core conversion functionality, get_supported_options provides metadata about available options, and validate_mermaid_syntax performs syntax validation. There is no overlap or ambiguity between these three functions.

    Naming Consistency5/5

    All tools follow a consistent snake_case naming pattern with clear verb-action structure: convert_mermaid_to_image, get_supported_options, and validate_mermaid_syntax. The naming is predictable and follows the same convention throughout.

    Tool Count4/5

    Three tools is a reasonable number for a Mermaid diagram conversion server, though it feels slightly minimal. The tools cover the essential operations (convert, validate, get options), but additional utilities like listing available themes or handling diagram editing might enhance completeness.

    Completeness4/5

    The tool set covers the core Mermaid conversion workflow well: conversion, syntax validation, and option discovery. Minor gaps include operations like batch conversion, diagram editing utilities, or theme management, but agents can work effectively with the provided tools for most use cases.

    Related MCP Connectors

    Related MCP Servers