Skip to main content
Glama
Mermaid MCP Server

Mermaid MCP Server

by wwwzhouhui

Mermaid MCP Server

Servidor de conversión de diagramas Mermaid basado en el Model Context Protocol (MCP), que proporciona potentes capacidades de generación de diagramas para clientes de IA

License Python MCP UV


Introducción al proyecto

Mermaid MCP Server es un servidor profesional de conversión de diagramas Mermaid basado en el Model Context Protocol (MCP), que ofrece potentes capacidades de generación de diagramas para clientes de IA. Este proyecto convierte código de diagramas Mermaid en archivos de imagen en múltiples formatos (PNG, JPG, SVG, PDF), permitiendo a los usuarios generar diagramas de alta calidad fácilmente en diversos clientes de IA compatibles con el protocolo MCP.

Características principales

  • Salida multi-formato: Compatible con PNG, JPG, SVG, PDF y otros formatos de imagen

  • Personalización de temas: Cuatro temas integrados: default, dark, neutral, forest

  • Opciones personalizables: Admite personalización de color de fondo, dimensiones de imagen, etc.

  • Validación de sintaxis: Proporciona validación de sintaxis Mermaid en tiempo real

  • Recursos de ejemplo: Códigos de ejemplo integrados para una amplia variedad de tipos de diagramas

  • Gestión de errores: Mecanismo completo de gestión de errores y mensajes de error amigables

  • Modo dual STDIO/SSE: Compatible con modos de comunicación STDIO y SSE

  • Gestión de paquetes uv: Utiliza el ultrarápido gestor de paquetes uv


Related MCP server: mcp-mermaid-validator

Lista de funciones

Nombre de la función

Descripción de la función

Stack tecnológico

Estado

Conversión de diagramas

Código Mermaid a imagen

mermaid.ink API

✅ Estable

Salida multi-formato

PNG/JPG/SVG/PDF

requests + base64

✅ Estable

Personalización de temas

4 temas integrados

mermaid.ink

✅ Estable

Validación de sintaxis

Verificación de sintaxis en tiempo real

mermaid-cli

✅ Estable

Recursos de ejemplo

Ejemplos variados de diagramas

Recursos estáticos

✅ Estable

Gestión de errores

Mensajes de error completos

Manejo de excepciones en Python

✅ Estable

Protocolo MCP

Model Context Protocol

mcp[cli]

✅ Estable

Modo SSE

Server-Sent Events

FastAPI + Uvicorn

✅ Estable


Arquitectura técnica

Tecnología

Versión

Uso

Python

3.12+

Lenguaje de desarrollo principal

MCP

1.9+

Model Context Protocol

FastAPI

0.104+

Framework web (modo SSE)

Uvicorn

0.24+

Servidor ASGI

requests

2.31+

Cliente HTTP

uv

latest

Gestor de paquetes de Python

Arquitectura de comunicación

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

Instrucciones de instalación

Requisitos del entorno

  • Python 3.12+

  • Gestor de paquetes uv (recomendado)

Instalación de dependencias

Opción 1: Instalación con uv (recomendada)

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

# 安装依赖
uv sync

Opción 2: Instalación con pip

pip install -r requirements.txt

Instrucciones de uso

Configuración del cliente

Configuración en Cursor

Añade la siguiente configuración al archivo ~/.cursor/mcp.json:

Modo STDIO (recomendado):

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

Modo SSE:

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

Configuración en Cherry Studio

  1. Abre Cherry Studio

  2. Ve a Configuración → MCP Servers → Añadir servidor

  3. Configura los parámetros:

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

    • Descripción: Servicio de generación de diagramas Mermaid

    • Tipo: STDIO

    • Comando: uvx

    • Parámetros: mermaid-mcp-server-png-pdf-jpg-svg

  4. Haz clic en guardar y activar

Ejemplo de configuración en Cherry Studio

Configuración en Claude Desktop

Añade lo siguiente al archivo claude_desktop_config.json:

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

Configuración en Continue.dev

Añade lo siguiente al archivo config.json:

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

Iniciar el servicio

Modo STDIO (recomendado para clientes de escritorio)

uv run python main.py

Modo SSE (para conexiones de red)

uv run python main.py --sse

Configuración

Configuración de variables de entorno

Nombre de la variable

Descripción

Valor predeterminado

HOST

Dirección del servidor

0.0.0.0

PORT

Puerto del servidor

8003

LOG_LEVEL

Nivel de registro

INFO

MERMAID_API_BASE_URL

Dirección de la API de Mermaid

https://mermaid.ink

REQUEST_TIMEOUT

Tiempo de espera de solicitud (segundos)

30

DEBUG

Modo de depuración

false

DEVELOPMENT_MODE

Modo de desarrollo

false


Herramientas disponibles

1. convert_mermaid_to_image

Convierte código de diagramas Mermaid en archivos de imagen en múltiples formatos

Parámetros:

  • mermaid_code (string): Código del diagrama Mermaid

  • output_format (string, opcional): Formato de salida, compatible con png, jpg, svg, pdf; por defecto "png"

  • theme (string, opcional): Estilo de tema, compatible con default, dark, neutral, forest; por defecto "default"

  • background_color (string, opcional): Color de fondo, código hexadecimal

  • width (number, opcional): Ancho de la imagen (píxeles)

  • height (number, opcional): Alto de la imagen (píxeles)

Formatos de salida compatibles: PNG, JPG, SVG, PDF

2. validate_mermaid_syntax

Valida la corrección sintáctica del código de diagramas Mermaid

Parámetros:

  • mermaid_code (string): Código del diagrama Mermaid a validar

Resultado devuelto:

  • valid (boolean): Si la validación es correcta

  • error_message (string): Mensaje de error (si la validación falla)

3. get_supported_options

Obtiene las opciones compatibles con el convertidor

Resultado devuelto:

  • themes (array): Lista de temas compatibles

  • formats (array): Lista de formatos compatibles


Tipos de diagramas compatibles

  • Diagrama de flujo (Flowchart): Para representar procesos y algoritmos

  • Diagrama de secuencia (Sequence Diagram): Para representar interacciones entre objetos

  • Diagrama de Gantt (Gantt Chart): Para la gestión de cronogramas de proyectos

  • Diagrama circular (Pie Chart): Para representar proporciones de datos

  • Grafo Git (Git Graph): Para representar el historial de commits de Git

  • Mapa mental (Mind Map): Para representar estructuras de conocimiento

  • Diagrama de clases (Class Diagram): Para representar estructuras de clases


Ejemplos de uso

Ejemplo de diagrama de flujo

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

Ejemplo de diagrama de secuencia

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

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

Ejemplo de validación de sintaxis

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

Recursos de ejemplo

Obtener ejemplos de diagramas

Puedes obtener ejemplos de diferentes tipos de diagramas mediante los siguientes URI de recursos:

  • mermaid://examples/flowchart - Ejemplo de diagrama de flujo

  • mermaid://examples/sequence - Ejemplo de diagrama de secuencia

  • mermaid://examples/gantt - Ejemplo de diagrama de Gantt

  • mermaid://examples/pie - Ejemplo de diagrama circular

  • mermaid://examples/gitgraph - Ejemplo de grafo Git

  • mermaid://examples/mindmap - Ejemplo de mapa mental

  • mermaid://examples/class - Ejemplo de diagrama de clases


Estructura del proyecto

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

Guía de desarrollo

Desarrollo local

# 克隆仓库
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

Modo de depuración

Activa la salida de registros detallada:

export LOG_LEVEL=DEBUG
uv run python main.py

Preguntas frecuentes

R:

  1. Comprueba la conexión de red y la configuración del cortafuegos

  2. Confirma que la API de mermaid.ink es accesible

  3. Comprueba la configuración del proxy

R:

  1. Usa la herramienta validate_mermaid_syntax para comprobar la sintaxis

  2. Consulta la documentación oficial de Mermaid

  3. Usa el código de los recursos de ejemplo

R:

  1. Simplifica el contenido del diagrama

  2. Divídelo en varios diagramas más pequeños

  3. Ajusta los parámetros de dimensiones de la imagen

R:

  1. Instala el gestor de paquetes uv: curl -LsSf https://astral.sh/uv/install.sh | sh

  2. O instala el paquete globalmente con pip

  3. Comprueba la variable de entorno PATH

R:

  1. Confirma que el servicio se ha iniciado en modo SSE

  2. Comprueba si el puerto 8003 está ocupado

  3. Confirma que la URL está configurada correctamente

R:

  1. Aumenta los parámetros de dimensiones de la imagen

  2. Elige un tema adecuado

  3. Optimiza la estructura del código Mermaid

R:

  1. Comprueba la velocidad de la conexión de red

  2. Aumenta la variable de entorno REQUEST_TIMEOUT

  3. Simplifica la complejidad del diagrama

R:

  1. Confirma que el nombre del tema está escrito correctamente

  2. Comprueba si el tema es compatible

  3. Prueba con un nombre de tema diferente

R:

  1. Usa el parámetro background_color

  2. El formato es un código de color hexadecimal (p. ej., #FFFFFF)

  3. Solo es compatible con algunos formatos de salida


Grupo de intercambio técnico

Te invitamos a unirte al grupo de intercambio técnico para compartir tus experiencias de uso y comentarios:

Grupo de intercambio técnico


Contacto con el autor

Código QR de WeChat


Donaciones

Si este proyecto te resulta útil, ¡invítame a un café ☕!

Pago con WeChat

Pago con WeChat


Historial de estrellas

Si te gusta el proyecto, ¡no dudes en darle una estrella ⭐!

Star History Chart


Licencia

Licencia MIT


Registro de cambios

v0.1.0 (versión actual)

  • ✅ Publicación de la versión inicial

  • ✅ Compatible con salida multi-formato PNG, JPG, SVG, PDF

  • ✅ Integra cuatro estilos de tema (default, dark, neutral, forest)

  • ✅ Proporciona funciones de validación de sintaxis y recursos de ejemplo

  • ✅ Compatible con comunicación en modo dual STDIO y SSE

v0.0.3 (2025-07-21)

  • ✅ Publicación de la versión inicial

  • ✅ Compatible con conversión de diagramas multi-formato

  • ✅ Función de validación de sintaxis

  • ✅ Función de recursos de ejemplo


Guía de contribución

¡Te invitamos a enviar Issues y Pull Requests para mejorar este proyecto!

  1. Haz un fork de este repositorio

  2. Crea una rama de funcionalidad: git checkout -b feature/amazing-feature

  3. Realiza los cambios: git commit -m 'Add amazing feature'

  4. Sube la rama: git push origin feature/amazing-feature

  5. Envía un Pull Request


Notas

  • La generación de diagramas puede tardar unos segundos, ten paciencia

  • Asegúrate de que la conexión de red funciona; el servicio depende de la API en línea de mermaid.ink

  • Los datos de imagen generados se devuelven en formato base64

  • Los diagramas complejos pueden requerir más tiempo de generación


¡Disfruta creando hermosos diagramas con 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