mermaid-render-mcp

mermaid-mcp

一个 MCP 服务，可将 Mermaid 图表渲染为 PNG、SVG 或 PDF，也可以将其转换为可编辑的 draw.io 文件。让你的大模型能够将图表语法转换为实际的图像和文档。

快速开始

Claude Code

claude mcp add mermaid -- npx -y mermaid-render-mcp

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "mermaid-render-mcp"]
    }
  }
}

**注意：**首次运行时会下载无头 Chromium（约 150 MB），因此初次启动需要几分钟。如果你只需要流程图，并且可以使用可编辑文件，那么 drawio 快速路径完全不需要 Chromium。

Docker

无需下载 Node.js 或 Chromium——镜像已包含所有内容（包括用于日文、中文和韩文标签的 CJK 字体）：

claude mcp add mermaid -- docker run -i --rm tcinebula/mermaid-render-mcp

要使用 output_path，请挂载一个主机目录并将文件写入其中：

{
  "mcpServers": {
    "mermaid": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "C:\\diagrams:/out", "tcinebula/mermaid-render-mcp"]
    }
  }
}

然后传入 output_path: "/out/figure.pdf"，文件就会出现在 C:\diagrams 中。

远程 / 可自托管（HTTP）

设置 PORT（或 MCP_TRANSPORT=http）后，同一服务会使用 Streamable HTTP，因此可直接通过 Dockerfile 部署到任意容器主机，例如 Railway、Fly.io：

• 端点：POST /mcp（健康检查位于 /healthz）
• 设置 AUTH_TOKEN，以要求提供 Authorization: Bearer <token>
• HTTP 模式下禁用 output_path；仅返回 base64/XML

从源码运行

git clone https://github.com/tci-nebula/mermaid-mcp.git
cd mermaid-mcp
npm install
claude mcp add mermaid -- node /path/to/mermaid-mcp/server.js

工具：render_diagram

参数	类型	默认值	描述
syntax	string	(必填)	Mermaid 图表定义
format	png | svg | pdf | drawio	png	输出格式（drawio = 可编辑的 draw.io XML，仅支持流程图）
theme	default | dark | neutral | forest	default	视觉主题
background	string	white	CSS 颜色或 transparent
width	number	1200	画布宽度（单位：px，仅适用于 PNG）
pdfFit	boolean	true	缩放 PDF 页面以适应图表（仅适用于 PDF）
output_path	string	—	将结果写入此文件路径，而不是返回 base64

返回 base64 编码的渲染图像，以便 MCP 客户端内嵌显示；也可以使用 output_path 将文件写入磁盘（适用于要打印或正式提交的 PDF）。

示例

向你的大模型提问：

“为我绘制一个 OAuth 登录流程图”

它会生成 Mermaid 语法、调用 render_diagram，然后返回一个 PNG。

drawio 快速路径（无需 Chromium）

format: "drawio" 是唯一完全不使用浏览器的输出格式。它完全由 JavaScript 实现——解析、使用 dagre 布局、生成 XML——因此无需下载 Chromium，无需安装约 150 MB 的内容，也不会有耗时数分钟的首次运行。转换几乎即时完成。

适用于以下情况：

• 你希望图表可编辑，而不是扁平图像——每个形状都保留为真正的 draw.io 对象
• 你使用资源受限的环境（CI、精简容器、受限制的笔记本电脑），不方便下载 Chromium
• 你只想立即获得图表，不需要栅格图像

{
  "syntax": "flowchart TD\n  A[Start] --> B{OK?}\n  B -->|yes| C[Ship]\n  B -->|no| A",
  "format": "drawio",
  "output_path": "flow.drawio"
}

在 draw.io（或 VS Code 扩展）中打开结果；如果需要图像，可在那里导出为 PNG/SVG/PDF——整个流程完全无需 Chromium。

限制

• 仅支持流程图。 flowchart 和 graph 图表可以转换；时序图、类图、状态图、ER 图和甘特图会报错。此类图表请使用 PNG/SVG/PDF。
• theme、background 和 width 会被忽略。 文件打开后，样式由 draw.io 负责。
• 节点尺寸为估算值，依据标签长度而非实际字体度量。draw.io 打开文件时会重新测量文本，使框的尺寸达到合适状态，但请将原始 XML 几何数据视为近似值。

支持的语法：方向 TD / TB / BT / LR / RL；形状 [rect]、(rounded)、{rhombus}、((circle))、([stadium])、[[subroutine]]、[(cylinder)]、{{hexagon}}；边 -->、---、-.->、==>、<-->，每种边都可以带有 |label|。

工作原理

PNG、SVG 和 PDF 渲染会通过 shell 调用 @mermaid-js/mermaid-cli（作为依赖项打包），并使用无头 Chromium 渲染图表。首次运行 npm install 会下载 Chromium（约 150 MB），因此需要几分钟。

draw.io 导出完全由 JavaScript 实现：流程图解析器和 dagre 布局引擎（与 Mermaid 使用的引擎相同）会生成原生 mxGraphModel XML，因此每个形状在 draw.io 中都可以单独编辑。

要求

• Node.js 18+

路线图

• PDF 导出（正式文档／法律文书工作流）
• draw.io XML 导出（可编辑图表——流程图）
• npm 包（mermaid-render-mcp）
• 远程托管服务选项（Streamable HTTP 传输）

许可证

MIT