Servidor MCP de Mermaid

Servidor de conversión de diagramas Mermaid basado en el Protocolo de Contexto de Modelo (MCP), que proporciona potentes capacidades de generación de diagramas para clientes de IA.

👁 Licencia
👁 Python
👁 MCP
👁 UV

Introducción al proyecto

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

Características principales

• Salida multiformato: Soporta múltiples formatos de imagen como PNG, JPG, SVG y PDF.

• Personalización de temas: Incluye cuatro temas integrados: default, dark, neutral y forest.

• Opciones personalizadas: Soporta la personalización de parámetros como el color de fondo y el tamaño de la imagen.

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

• Recursos de ejemplo: Incluye una amplia variedad de códigos de ejemplo para diferentes tipos de diagramas.

• Manejo de errores: Mecanismo completo de manejo de errores y mensajes de error amigables.

• Modo dual STDIO/SSE: Soporta modos de comunicación STDIO y SSE.

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

Related MCP server: mcp-mermaid-validator

Lista de funciones

Arquitectura técnica

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 mediante uv (recomendado)

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

# 安装依赖
uv sync

Opción 2: Instalación mediante pip

pip install -r requirements.txt

Instrucciones de uso

Configuración del cliente

Configuración de Cursor

Agregue la siguiente configuración en el 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 de Cherry Studio

1. Abra Cherry Studio

2. Vaya a Configuración → Servidores MCP → Agregar servidor

3. Configure 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. Haga clic en guardar y activar

👁 Ejemplo de configuración de Cherry Studio

Configuración de Claude Desktop

Agregue lo siguiente en el 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 de Continue.dev

Agregue lo siguiente en el 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

Notas de configuración

Configuración de variables de entorno

Herramientas disponibles

1. convert_mermaid_to_image

Convierte código de diagrama Mermaid a archivos de imagen en varios formatos.

Parámetros:

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

• output_format (string, opcional): Formato de salida, soporta png, jpg, svg, pdf, predeterminado "png"

• theme (string, opcional): Estilo del tema, soporta default, dark, neutral, forest, predeterminado "default"

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

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

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

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

2. validate_mermaid_syntax

Valida la corrección sintáctica del código del diagrama Mermaid.

Parámetros:

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

Resultado devuelto:

• valid (boolean): Si la validación fue exitosa

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

3. get_supported_options

Obtiene las opciones soportadas por el convertidor.

Resultado devuelto:

• themes (array): Lista de temas soportados

• formats (array): Lista de formatos soportados

Tipos de diagramas soportados

• 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 del progreso del proyecto

• Gráfico circular (Pie Chart): Para representar proporciones de datos

• Gráfico 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 生成图表

Ejemplos de recursos

Obtener ejemplos de diagramas

Se pueden obtener ejemplos de diferentes tipos de diagramas a través de 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 gráfico circular

• mermaid://examples/gitgraph - Ejemplo de gráfico 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

Habilitar salida de registro detallada:

export LOG_LEVEL=DEBUG
uv run python main.py

Preguntas frecuentes

R:

1. Verifique la conexión de red y la configuración del firewall

2. Confirme que la API mermaid.ink sea accesible

3. Verifique la configuración del proxy

R:

1. Use la herramienta validate_mermaid_syntax para verificar la sintaxis

2. Consulte la documentación oficial de Mermaid

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

R:

1. Simplifique el contenido del diagrama

2. Divídalo en varios diagramas pequeños

3. Ajuste los parámetros de tamaño de la imagen

R:

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

2. O use la instalación global de paquetes con pip

3. Verifique la variable de entorno PATH

R:

1. Confirme que el servicio se haya iniciado en modo SSE

2. Verifique si el puerto 8003 está ocupado

3. Confirme que la configuración de la URL sea correcta

R:

1. Aumente los parámetros de tamaño de la imagen

2. Seleccione un tema adecuado

3. Optimice la estructura del código Mermaid

R:

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

2. Aumente la variable de entorno REQUEST_TIMEOUT

3. Simplifique la complejidad del diagrama

R:

1. Confirme que el nombre del tema esté escrito correctamente

2. Verifique si el tema es compatible

3. Intente usar un nombre de tema diferente

R:

1. Use el parámetro background_color

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

3. Solo es compatible con algunos formatos de salida

Grupo de intercambio técnico

Bienvenido a unirse al grupo de intercambio técnico para compartir sus experiencias y sugerencias:

👁 WeChat_20260501235133_120_6

Contacto del autor

• WeChat: laohaibao2025

• Correo electrónico: 75271002@qq.com

👁 Código QR de WeChat

Donaciones

Si este proyecto te ha sido útil, te invito a invitarme a un café ☕

Pago por WeChat

👁 Pago por WeChat

Historial de estrellas

Si te gusta el proyecto, ¡agradecería una estrella ⭐!

👁 Gráfico de historial de estrellas

Licencia

Licencia MIT

Registro de cambios

v0.1.0 (versión actual)

• ✅ Lanzamiento de la versión inicial

• ✅ Soporte para salida multiformato PNG, JPG, SVG, PDF

• ✅ Integración de cuatro estilos de tema (default, dark, neutral, forest)

• ✅ Funciones de validación de sintaxis y recursos de ejemplo

• ✅ Soporte para comunicación en modo dual STDIO y SSE

v0.0.3 (2025-07-21)

• ✅ Lanzamiento de la versión inicial

• ✅ Soporte para conversión de diagramas multiformato

• ✅ Función de validación de sintaxis

• ✅ Función de recursos de ejemplo

Guía de contribución

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

1. Haz un Fork de este repositorio

2. Crea una rama de características: git checkout -b feature/amazing-feature

3. Envía tus cambios: git commit -m 'Add amazing feature'

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

5. Envía un Pull Request

Notas importantes

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

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

• Los datos de la imagen generada se devuelven en formato base64

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

¡Disfruta creando hermosos diagramas con Mermaid! 🎨✨

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• convert_mermaid_to_imageA
• get_supported_optionsA
• validate_mermaid_syntaxB