Mermaid MCP Server
wwwzhouhui/mermaid_mcp_server
Converta diagramas Mermaid em imagens PNG/JPG/SVG/PDF via MCP
Ver no GitHubServidor MCP que converte código Mermaid em múltiplos formatos de imagem (PNG, JPG, SVG, PDF) com suporte a temas e customizações. Integra-se nativamente a clientes AI via protocolo MCP, oferecendo validação de sintaxe e tratamento robusto de erros.
Instalação
npx convez-ai wwwzhouhui/mermaid_mcp_server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar diagramas e fluxogramas automaticamente em documentos
- Converter code-as-diagram em múltiplos formatos para apresentações
- Integrar geração de gráficos em fluxos de trabalho com IA
Veredito

Ferramenta sólida para automatizar a geração de diagramas Mermaid em ambientes MCP. Bem arquitetada com suporte STDIO/SSE, mas depende de mermaid.ink externo e requer configuração manual em clientes.
README
A tradução para o português deste README ainda está na fila.
Mermaid MCP Server
基于 Model Context Protocol (MCP) 的 Mermaid 图表转换服务器,为 AI 客户端提供强大的图表生成能力
项目介绍
Mermaid MCP Server 是一个专业的基于 Model Context Protocol (MCP) 的 Mermaid 图表转换服务器,为 AI 客户端提供强大的图表生成能力。该项目能够将 Mermaid 图表代码转换为多种格式的图像文件(PNG、JPG、SVG、PDF),让用户能够在支持 MCP 协议的各种 AI 客户端中轻松生成高质量的图表。
核心特性
- 多格式输出: 支持 PNG、JPG、SVG、PDF 等多种图像格式
- 主题定制: 内置 default、dark、neutral、forest 四种精美主题
- 自定义选项: 支持背景颜色、图像尺寸等参数自定义
- 语法验证: 提供实时的 Mermaid 语法验证功能
- 示例资源: 内置丰富的图表类型示例代码
- 错误处理: 完善的错误处理机制和友好的错误提示
- STDIO/SSE 双模式: 支持 STDIO 和 SSE 两种通信模式
- uv 包管理: 使用超快的 uv 包管理器
功能清单
| 功能名称 | 功能说明 | 技术栈 | 状态 |
|---|---|---|---|
| 图表转换 | Mermaid 代码转图像 | mermaid.ink API | ✅ 稳定 |
| 多格式输出 | PNG/JPG/SVG/PDF | requests + base64 | ✅ 稳定 |
| 主题定制 | 4 种内置主题 | mermaid.ink | ✅ 稳定 |
| 语法验证 | 实时语法检查 | mermaid-cli | ✅ 稳定 |
| 示例资源 | 丰富图表示例 | 静态资源 | ✅ 稳定 |
| 错误处理 | 完善错误提示 | Python 异常处理 | ✅ 稳定 |
| MCP 协议 | Model Context Protocol | mcp[cli] | ✅ 稳定 |
| SSE 模式 | Server-Sent Events | FastAPI + Uvicorn | ✅ 稳定 |
技术架构
| 技术 | 版本 | 用途 |
|---|---|---|
| Python | 3.12+ | 主要开发语言 |
| MCP | 1.9+ | Model Context Protocol |
| FastAPI | 0.104+ | Web 框架(SSE 模式) |
| Uvicorn | 0.24+ | ASGI 服务器 |
| requests | 2.31+ | HTTP 客户端 |
| uv | latest | Python 包管理器 |
通信架构
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 通信架构图 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌─────────────────────────┐ ┌─────────────┐ │
│ │ AI 客户端 │ ◄────► │ Mermaid MCP Server │ ◄────► │ Mermaid API │ │
│ │ (Cursor/Claude) │ │ STDIO/SSE │ │ mermaid.ink│ │
│ └──────────────────┘ └─────────────────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ AI 对话界面 MCP 协议通信 图表渲染转换 │
│ 生成图表请求 双向数据传输 返回图像数据 │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
安装说明
环境要求
- Python 3.12+
- uv 包管理器(推荐)
安装依赖
方式一:使用 uv 安装(推荐)
# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server
# 安装依赖
uv sync
方式二:使用 pip 安装
pip install -r requirements.txt
使用说明
客户端配置
Cursor 配置
在 ~/.cursor/mcp.json 文件中添加以下配置:
STDIO 模式(推荐):
{
"mcpServers": {
"mermaid-mcp-server-png-pdf-jpg-svg": {
"command": "uvx",
"args": [
"mermaid-mcp-server-png-pdf-jpg-svg"
]
}
}
}
SSE 模式:
{
"mcpServers": {
"mermaid-mcp-server-png-pdf-jpg-svg": {
"url": "http://127.0.0.1:8003/sse"
}
}
}
Cherry Studio 配置
- 打开 Cherry Studio
- 进入 设置 → MCP Servers → 添加服务器
- 配置参数:
- 名称:
mermaid-mcp-server-png-pdf-jpg-svg - 描述:
Mermaid 图表生成服务 - 类型:
STDIO - 命令:
uvx - 参数:
mermaid-mcp-server-png-pdf-jpg-svg
- 名称:
- 点击保存并启用

Claude Desktop 配置
在 claude_desktop_config.json 文件中添加:
{
"mcpServers": {
"mermaid-mcp-server-png-pdf-jpg-svg": {
"command": "uvx",
"args": [
"mermaid-mcp-server-png-pdf-jpg-svg"
]
}
}
}
Continue.dev 配置
在 config.json 文件中添加:
{
"mcpServers": {
"mermaid-mcp-server-png-pdf-jpg-svg": {
"command": "uvx",
"args": [
"mermaid-mcp-server-png-pdf-jpg-svg"
]
}
}
}
启动服务
STDIO 模式(推荐用于桌面客户端)
uv run python main.py
SSE 模式(用于网络连接)
uv run python main.py --sse
配置说明
环境变量配置
| 变量名 | 说明 | 默认值 |
|---|---|---|
HOST | 服务器地址 | 0.0.0.0 |
PORT | 服务器端口 | 8003 |
LOG_LEVEL | 日志级别 | INFO |
MERMAID_API_BASE_URL | Mermaid API 地址 | https://mermaid.ink |
REQUEST_TIMEOUT | 请求超时时间(秒) | 30 |
DEBUG | 调试模式 | false |
DEVELOPMENT_MODE | 开发模式 | false |
可用工具
1. convert_mermaid_to_image
将 Mermaid 图表代码转换为多种格式的图像文件
参数:
mermaid_code(string): Mermaid 图表代码output_format(string, 可选): 输出格式,支持 png、jpg、svg、pdf,默认 "png"theme(string, 可选): 主题样式,支持 default、dark、neutral、forest,默认 "default"background_color(string, 可选): 背景颜色,十六进制代码width(number, 可选): 图像宽度(像素)height(number, 可选): 图像高度(像素)
支持的输出格式: PNG、JPG、SVG、PDF
2. validate_mermaid_syntax
验证 Mermaid 图表代码的语法正确性
参数:
mermaid_code(string): 需要验证的 Mermaid 图表代码
返回结果:
valid(boolean): 是否验证通过error_message(string): 错误信息(如果验证失败)
3. get_supported_options
获取转换器支持的选项
返回结果:
themes(array): 支持的主题列表formats(array): 支持的格式列表
支持的图表类型
- 流程图 (Flowchart): 用于表示流程和算法
- 时序图 (Sequence Diagram): 用于表示对象之间的交互
- 甘特图 (Gantt Chart): 用于项目进度管理
- 饼图 (Pie Chart): 用于表示数据占比
- Git 图 (Git Graph): 用于表示 Git 提交历史
- 思维导图 (Mind Map): 用于表示知识结构
- 类图 (Class Diagram): 用于表示类结构
使用示例
流程图示例
请使用 convert_mermaid_to_image 工具生成一个流程图:
flowchart TD
A[开始] --> B{判断条件}
B -->|是 | C[执行动作 1]
B -->|否 | D[执行动作 2]
C --> E[结束]
D --> E
时序图示例
请使用 convert_mermaid_to_image 工具生成一个时序图,使用深色主题:
sequenceDiagram
participant 用户
participant 系统
participant 数据库
用户->>系统:登录请求
系统->>数据库:验证用户
数据库-->>系统:返回结果
系统-->>用户:登录成功
语法验证示例
首先使用 validate_mermaid_syntax 验证语法,然后使用 convert_mermaid_to_image 生成图表
资源示例
获取图表示例
可以通过以下资源 URI 获取不同类型的图表示例:
mermaid://examples/flowchart- 流程图示例mermaid://examples/sequence- 时序图示例mermaid://examples/gantt- 甘特图示例mermaid://examples/pie- 饼图示例mermaid://examples/gitgraph- Git 图示例mermaid://examples/mindmap- 思维导图示例mermaid://examples/class- 类图示例
项目结构
mermaid_mcp_server/
├── mermaid_mcp_server/ # 核心模块
│ ├── __init__.py
│ └── main.py # 主程序入口
├── requirements.txt # 依赖列表(pip)
├── pyproject.toml # 项目配置(uv)
├── .env.example # 环境变量示例
├── README.md # 项目文档
└── .vscode/ # VSCode 配置
└── settings.json
开发指南
本地开发
# 克隆仓库
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
调试模式
启用详细日志输出:
export LOG_LEVEL=DEBUG
uv run python main.py
常见问题
A:
- 检查网络连接和防火墙设置
- 确认 mermaid.ink API 可访问
- 检查代理设置
A:
- 使用 validate_mermaid_syntax 工具检查语法
- 参考 Mermaid 官方文档
- 使用示例资源中的代码
A:
- 简化图表内容
- 分割为多个小图表
- 调整图像尺寸参数
A:
- 安装 uv 包管理器:
curl -LsSf https://astral.sh/uv/install.sh | sh - 或使用 pip 全局安装包
- 检查 PATH 环境变量
A:
- 确认服务已以 SSE 模式启动
- 检查端口 8003 是否被占用
- 确认 URL 配置正确
A:
- 增加图像尺寸参数
- 选择合适的主题
- 优化 Mermaid 代码结构
A:
- 检查网络连接速度
- 增加 REQUEST_TIMEOUT 环境变量
- 简化图表复杂度
A:
- 确认主题名称拼写正确
- 检查是否支持该主题
- 尝试使用不同的主题名称
A:
- 使用 background_color 参数
- 格式为十六进制颜色代码(如 #FFFFFF)
- 仅支持部分输出格式
技术交流群
欢迎加入技术交流群,分享你的使用心得和反馈建议:

作者联系
- 微信: laohaibao2025
- 邮箱: 75271002@qq.com

打赏
如果这个项目对你有帮助,欢迎请我喝杯咖啡 ☕
微信支付

Star History
如果觉得项目不错,欢迎点个 Star ⭐
License
MIT License
更新日志
v0.1.0 (当前版本)
- ✅ 初始版本发布
- ✅ 支持 PNG、JPG、SVG、PDF 多格式输出
- ✅ 集成四种主题样式(default、dark、neutral、forest)
- ✅ 提供语法验证和示例资源功能
- ✅ 支持 STDIO 和 SSE 双模式通信
v0.0.3 (2025-07-21)
- ✅ 初始版本发布
- ✅ 支持多格式图表转换
- ✅ 语法验证功能
- ✅ 示例资源功能
贡献指南
欢迎提交 Issue 和 Pull Request 来改进这个项目!
- Fork 本仓库
- 创建特性分支:
git checkout -b feature/amazing-feature - 提交更改:
git commit -m 'Add amazing feature' - 推送到分支:
git push origin feature/amazing-feature - 提交 Pull Request
注意事项
- 图表生成可能需要几秒钟时间,请耐心等待
- 确保网络连接正常,服务依赖 mermaid.ink 在线 API
- 生成的图像数据以 base64 格式返回
- 复杂图表可能需要更长的生成时间
Enjoy creating beautiful diagrams with Mermaid! 🎨✨