Mermaid MCP Server

Mermaid MCP 服务

一个可将 Mermaid 图表转换为 PNG 图片或 SVG 文件的模型上下文协议（MCP）服务。此服务允许 AI 助手和其他应用使用 Mermaid Markdown 语法，根据文本描述生成可视化图表。

功能

• 将 Mermaid 图表代码转换为 PNG 图片或 SVG 文件
• 支持多种图表主题（default、forest、dark、neutral）
• 可自定义背景颜色
• 使用 Puppeteer 实现高质量的无头浏览器渲染
• 实现 MCP 协议，可与 AI 助手无缝集成
• 输出选项灵活：直接返回图片/SVG 或保存到磁盘
• 提供包含详细错误信息的错误处理

工作原理

此服务使用 Puppeteer 启动无头浏览器，将 Mermaid 图表渲染为 SVG，并可选择截取渲染后图表的屏幕截图。流程包括：

1. 启动无头浏览器实例
2. 使用 Mermaid 代码创建 HTML 模板
3. 加载 Mermaid.js 库
4. 将图表渲染为 SVG
5. 直接保存 SVG，或将其截屏为 PNG
6. 直接返回图片/SVG，或将其保存到磁盘

要求

• Node.js 22.12.0 或更高版本

安全提示： 0.3.0 之前的版本依赖存在已知漏洞的 Puppeteer 和 Mermaid 版本。请升级到 0.3.0 或更高版本。以下配置使用 @latest，以便 npx 获取新版本。

构建

npx tsc

用法

与 Claude 桌面版搭配使用

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "@peng-shawn/mermaid-mcp-server@latest"]
    }
  }
}

与 Cursor 和 Cline 搭配使用

env CONTENT_IMAGE_SUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server@latest

你可以在 ./diagrams 下找到 Mermaid 图表列表。这些图表由 Cursor agent 使用以下提示词创建：“生成 Mermaid 图表并将其保存到单独的 diagrams 文件夹中，以说明 renderMermaidPng 的工作原理”

使用 inspector 运行

使用 inspector 运行服务，以便测试和调试：

npx @modelcontextprotocol/inspector node dist/index.js

服务将启动并通过 stdio 监听 MCP 协议消息。

点击此处了解有关 inspector 的更多信息。

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Mermaid Diagram Generator：

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

Docker 和 Smithery 环境

在 Docker 容器中运行时（包括通过 Smithery 运行），你可能需要处理 Chrome 依赖项：

1. 服务现在默认尝试使用 Puppeteer 自带的浏览器

2. 如果遇到与浏览器相关的错误，可以选择以下两种方案：

   方案 1：构建 Docker 镜像时：

   • 安装 Puppeteer 时设置 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
   • 在 Docker 容器中安装 Chrome/Chromium
   • 在运行时设置 PUPPETEER_EXECUTABLE_PATH，指向 Chrome 的安装位置

   方案 2：使用 Puppeteer 自带的 Chrome：

   • 确保 Docker 容器具备 Chrome 所需的依赖项
   • 无需设置 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD
   • 代码将自动使用自带的浏览器

对于 Smithery 用户，最新版本无需额外配置即可正常运行。

API

该服务提供一个工具：

• generate：将 Mermaid 图表代码转换为 PNG 图像或 SVG 文件
  • 参数：
    • code：要渲染的 Mermaid 图表代码
    • theme：（可选）图表主题。可选项："default"、"forest"、"dark"、"neutral"
    • backgroundColor：（可选）图表背景颜色，例如 'white'、'transparent'、'#F0F0F0'
    • outputFormat：（可选）图表输出格式。可选项："png"、"svg"（默认为 "png"）
    • name：生成文件的名称（当 CONTENT_IMAGE_SUPPORTED=false 时必填）
    • folder：保存图像/SVG 的绝对路径（当 CONTENT_IMAGE_SUPPORTED=false 时必填）

generate 工具的行为取决于 CONTENT_IMAGE_SUPPORTED 环境变量：

• 当 CONTENT_IMAGE_SUPPORTED=true（默认值）时：工具会在响应中直接返回图像/SVG
• 当 CONTENT_IMAGE_SUPPORTED=false 时：工具会将图像/SVG 保存到指定文件夹，并返回文件路径

环境变量

• CONTENT_IMAGE_SUPPORTED：控制图像是直接在响应中返回还是保存到磁盘
  • true（默认值）：图像会直接在响应中返回
  • false：图像会保存到磁盘，因此需要提供 name 和 folder 参数

示例

基本用法

// Generate a flowchart with default settings
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

设置主题和背景颜色

// Generate a sequence diagram with forest theme and light gray background
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

保存到磁盘（当 CONTENT_IMAGE_SUPPORTED=false 时）

// Generate a class diagram and save it to disk as PNG
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

生成 SVG 输出

// Generate a state diagram as SVG
{
  "code": "stateDiagram-v2\n    [*] --> Still\n    Still --> [*]\n    Still --> Moving\n    Moving --> Still\n    Moving --> Crash\n    Crash --> [*]",
  "outputFormat": "svg",
  "name": "state_diagram",
  "folder": "/path/to/diagrams"
}

常见问题

Claude 桌面版不是已经通过 canvas 支持 mermaid 了吗？

是的，但它不支持 theme 和 backgroundColor 选项。此外，使用专用服务可以更轻松地通过不同的 MCP 客户端创建 mermaid 图表。

为什么使用 Cursor 时需要指定 CONTENT_IMAGE_SUPPORTED=false？

Cursor 尚不支持在响应中内嵌图像。

发布

本项目使用 GitHub Actions 自动将项目发布到 npm。

方法 1：使用发布脚本（推荐）

1. 确保所有更改都已提交并推送

2. 使用指定版本号或语义化版本增量运行发布脚本：

   # Using a specific version number
   npm run release 0.1.4
   
   # Using semantic version increments
   npm run release patch  # Increments the patch version (e.g., 0.1.3 → 0.1.4)
   npm run release minor  # Increments the minor version (e.g., 0.1.3 → 0.2.0)
   npm run release major  # Increments the major version (e.g., 0.1.3 → 1.0.0)
   

3. 脚本将会：

   • 验证版本格式或语义化版本增量
   • 检查当前是否位于 main 分支
   • 检测文件之间的版本不一致，并发出警告
   • 统一更新所有版本引用（package.json、package-lock.json 和 index.ts）
   • 使用所有版本更改创建一个提交
   • 创建并推送 git 标签
   • 随后，GitHub 工作流将自动构建并发布到 npm

方法 2：手动操作

1. 更新代码并提交更改
2. 使用版本号创建并推送新标签：

   git tag v0.1.4  # Use the appropriate version number
   git push origin v0.1.4
   

3. GitHub 工作流将自动：
   • 构建项目
   • 使用标签中的版本号发布到 npm

注意：你需要在 GitHub 仓库设置中配置 NPM_TOKEN 密钥。操作步骤如下：

1. 生成具有发布权限的 npm 访问令牌
2. 前往 GitHub 仓库 → Settings → Secrets and variables → Actions
3. 创建名为 NPM_TOKEN 的新仓库密钥，并将 npm 令牌设为其值

徽章

许可证

MIT