Mermaid MCP Server
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
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 syncOpción 2: Instalación con pip
pip install -r requirements.txtInstrucciones 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
Abre Cherry Studio
Ve a Configuración → MCP Servers → Añadir servidor
Configura los parámetros:
Nombre:
mermaid-mcp-server-png-pdf-jpg-svgDescripción:
Servicio de generación de diagramas MermaidTipo:
STDIOComando:
uvxParámetros:
mermaid-mcp-server-png-pdf-jpg-svg
Haz clic en guardar y activar

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.pyModo SSE (para conexiones de red)
uv run python main.py --sseConfiguración
Configuración de variables de entorno
Nombre de la variable | Descripción | Valor predeterminado |
| Dirección del servidor |
|
| Puerto del servidor |
|
| Nivel de registro |
|
| Dirección de la API de Mermaid |
|
| Tiempo de espera de solicitud (segundos) |
|
| Modo de depuración |
|
| Modo de desarrollo |
|
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 Mermaidoutput_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 hexadecimalwidth(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 correctaerror_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 compatiblesformats(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 --> EEjemplo 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 flujomermaid://examples/sequence- Ejemplo de diagrama de secuenciamermaid://examples/gantt- Ejemplo de diagrama de Ganttmermaid://examples/pie- Ejemplo de diagrama circularmermaid://examples/gitgraph- Ejemplo de grafo Gitmermaid://examples/mindmap- Ejemplo de mapa mentalmermaid://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.jsonGuí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 --sseModo de depuración
Activa la salida de registros detallada:
export LOG_LEVEL=DEBUG
uv run python main.pyPreguntas frecuentes
R:
Comprueba la conexión de red y la configuración del cortafuegos
Confirma que la API de mermaid.ink es accesible
Comprueba la configuración del proxy
R:
Usa la herramienta validate_mermaid_syntax para comprobar la sintaxis
Consulta la documentación oficial de Mermaid
Usa el código de los recursos de ejemplo
R:
Simplifica el contenido del diagrama
Divídelo en varios diagramas más pequeños
Ajusta los parámetros de dimensiones de la imagen
R:
Instala el gestor de paquetes uv:
curl -LsSf https://astral.sh/uv/install.sh | shO instala el paquete globalmente con pip
Comprueba la variable de entorno PATH
R:
Confirma que el servicio se ha iniciado en modo SSE
Comprueba si el puerto 8003 está ocupado
Confirma que la URL está configurada correctamente
R:
Aumenta los parámetros de dimensiones de la imagen
Elige un tema adecuado
Optimiza la estructura del código Mermaid
R:
Comprueba la velocidad de la conexión de red
Aumenta la variable de entorno REQUEST_TIMEOUT
Simplifica la complejidad del diagrama
R:
Confirma que el nombre del tema está escrito correctamente
Comprueba si el tema es compatible
Prueba con un nombre de tema diferente
R:
Usa el parámetro background_color
El formato es un código de color hexadecimal (p. ej., #FFFFFF)
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:

Contacto con el autor
WeChat: laohaibao2025
Correo electrónico: 75271002@qq.com

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

Historial de estrellas
Si te gusta el proyecto, ¡no dudes en darle una estrella ⭐!
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!
Haz un fork de este repositorio
Crea una rama de funcionalidad:
git checkout -b feature/amazing-featureRealiza los cambios:
git commit -m 'Add amazing feature'Sube la rama:
git push origin feature/amazing-featureEnví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 toolsconvert_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
Scored across 3 tools
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.
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.
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.
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
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Related MCP Servers
- AlicenseBqualityBmaintenanceA Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images.1301 npm234MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that validates and renders Mermaid diagrams.157MIT
- AlicenseNot gradedqualityNot gradedmaintenanceA server that implements the Model Context Protocol (MCP), providing an interface for LLM applications to generate mermaid.js visualizations and diagrams.MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that converts SVG code to PNG images, offering two conversion methods (CairoSVG and Inkscape) with support for custom working directories.3-