Skip to main content
Glama
deenesjakoruzh
wwwzhouhui

Mermaid MCP Server

by wwwzhouhui
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

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

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: 图像高度（像素，可选）

返回:
    包含转换后图像数据和元数据的字典
ParametersJSON Schema
NameRequiredDescriptionDefault
mermaid_codeYes
output_formatNopng
themeNodefault
background_colorNo
widthNo
heightNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It mentions the tool converts code to images and returns a dictionary with data and metadata, but lacks details on error handling, performance (e.g., rate limits), authentication needs, or side effects. This is inadequate for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a structured list of parameters and return value. Every sentence earns its place with no redundant information, making it efficient and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, mutation operation) and no annotations, the description does well by detailing all parameters and noting the return structure. However, it lacks behavioral context like error cases or limitations. The presence of an output schema mitigates some gaps, but more completeness is needed for a mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides detailed semantics for all 6 parameters beyond the schema, including explanations of mermaid_code, output_format options, theme options, background_color syntax, and optional width/height. This adds significant value over the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('将 Mermaid 图表代码转换为多种格式的图像') with the resource (Mermaid chart code) and distinguishes from siblings by focusing on conversion rather than validation or option retrieval. It explicitly lists the output formats, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying what the tool does, but does not explicitly state when to use it versus alternatives like validate_mermaid_syntax or get_supported_options. No guidance on prerequisites or exclusions is provided, leaving usage context partially inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a dictionary with lists of supported themes and formats, which adds behavioral context beyond the input schema (which has no parameters). However, it doesn't cover other traits like performance, error handling, or authentication needs, leaving gaps in transparency for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured: two sentences that directly state the purpose and return value, with no wasted words. It's front-loaded with the core function, and every sentence adds essential information, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no annotations, but with an output schema), the description is reasonably complete. It explains what the tool does and the return format, which complements the output schema. However, it lacks usage context and some behavioral details, preventing a perfect score despite the structured support.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the input schema description coverage is 100% (with an empty schema). The description doesn't need to add parameter semantics, so it appropriately focuses on the return value. Since there are no parameters to document, a baseline score of 4 is justified, as the description doesn't introduce confusion or redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '获取转换器支持的选项，如图表主题和输出格式' (Get converter-supported options, such as chart themes and output formats). It specifies both the action ('获取' - get) and the resource ('支持的选项' - supported options), with concrete examples. However, it doesn't explicitly differentiate from sibling tools like 'convert_mermaid_to_image' or 'validate_mermaid_syntax', which prevents a score of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or suggest scenarios where this tool is appropriate (e.g., before conversion to check available options). Without any usage context or exclusions, it relies on implicit understanding, which is insufficient for clear agent decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

返回:
    包含验证结果的字典
ParametersJSON Schema
NameRequiredDescriptionDefault
mermaid_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions '尝试简单转换' (attempting simple conversion) as the validation method, which implies a read-only, non-destructive operation, but doesn't clarify error handling, performance implications, or what '简单转换' entails. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured: a purpose statement followed by clear parameter and return sections in bullet-like format. Every sentence earns its place without redundancy, and it's front-loaded with the core functionality. The bilingual presentation (Chinese purpose, English labels) is efficient for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single parameter, no nested objects) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers purpose, parameter semantics, and return type at a high level. However, it lacks usage guidelines and detailed behavioral context, which are minor gaps in this simple validation context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly documents the single parameter 'mermaid_code' as '要验证的 Mermaid 图表语法代码' (Mermaid diagram syntax code to validate), adding meaning beyond the schema's basic title 'Mermaid Code'. However, with schema description coverage at 0%, it doesn't provide format details, constraints, or examples. The baseline is 3 since it compensates somewhat but not fully for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as '验证 Mermaid 图表语法' (validate Mermaid diagram syntax) and specifies the method '通过尝试简单转换' (by attempting simple conversion). It distinguishes from sibling tools like 'convert_mermaid_to_image' by focusing on validation rather than conversion to image format. However, it doesn't explicitly differentiate from 'get_supported_options' which might relate to syntax options.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools 'convert_mermaid_to_image' or 'get_supported_options', nor does it specify scenarios where validation is preferred over direct conversion or option checking. There's no indication of prerequisites or exclusions for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
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.

Maintenance

ActivityActive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wwwzhouhui/mermaid_mcp_server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server