Mermaid MCP Server
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 包管理器
Related MCP server: mcp-mermaid-validator
功能清单
功能名称 | 功能说明 | 技术栈 | 状态 |
图表转换 | 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.pySSE 模式(用于网络连接)
uv run python main.py --sse配置说明
环境变量配置
变量名 | 说明 | 默认值 |
| 服务器地址 |
|
| 服务器端口 |
|
| 日志级别 |
|
| Mermaid API 地址 |
|
| 请求超时时间(秒) |
|
| 调试模式 |
|
| 开发模式 |
|
可用工具
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! 🎨✨
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: 图像高度(像素,可选)
返回:
包含转换后图像数据和元数据的字典
| Name | Required | Description | Default |
|---|---|---|---|
| mermaid_code | Yes | ||
| output_format | No | png | |
| theme | No | default | |
| background_color | No | ||
| width | No | ||
| height | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
获取转换器支持的选项,如图表主题和输出格式。
返回:
一个包含支持的主题和格式列表的字典。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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 图表语法代码
返回:
包含验证结果的字典
| Name | Required | Description | Default |
|---|---|---|---|
| mermaid_code | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
- First observed
convert_mermaid_to_image - First observed
get_supported_options - First observed
validate_mermaid_syntax
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.
Maintenance
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
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images.1109 npm234MIT
- AlicenseBqualityCmaintenanceA Model Context Protocol server that validates and renders Mermaid diagrams.1183 npm57MIT
- 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-