Mermaid MCP 服务器

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。此服务器允许 AI 助手和其他应用程序使用 Mermaid markdown 语法从文本描述生成可视化图表。

特性

• 将 Mermaid 图表代码转换为 PNG 图像
• 支持多种图表主题（默认、森林、黑暗、中性）
• 可自定义的背景颜色
• 使用 Puppeteer 进行高质量的无头浏览器渲染
• 实现了 MCP 协议，可与 AI 助手无缝集成
• 灵活的输出选项：直接返回图像或保存到磁盘
• 错误处理，提供详细的错误消息

工作原理

该服务器使用 Puppeteer 启动一个无头浏览器，将 Mermaid 图表渲染为 SVG，并捕获渲染图表的屏幕截图。该过程包括：

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

构建

npx tsc

用法

与 Claude desktop 一起使用

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

与 Cursor 和 Cline 一起使用

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

您可以在 ./diagrams 下找到 mermaid 图表的列表，它们是使用 Cursor agent 和提示语 "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work" 创建的。

使用 inspector 运行

使用 inspector 运行服务器以进行测试和调试：

npx @modelcontextprotocol/inspector node dist/index.js

服务器将启动并监听 stdio 上的 MCP 协议消息。

在此处了解有关 inspector 的更多信息：https://modelcontextprotocol.io/docs/tools/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 图像
  • 参数：
    • code：要渲染的 Mermaid 图表代码
    • theme：（可选）图表的主题。选项："default"、"forest"、"dark"、"neutral"
    • backgroundColor：（可选）图表的背景颜色，例如 'white'、'transparent'、'#F0F0F0'
    • name：生成文件的名称（当 CONTENT_IMAGE_SUPPORTED=false 时是必需的）
    • folder：保存图像的绝对路径（当 CONTENT_IMAGE_SUPPORTED=false 时是必需的）

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

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

环境变量

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

示例

基本用法

// 使用默认设置生成流程图
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

使用主题和背景颜色

// 生成具有森林主题和浅灰色背景的序列图
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

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

// 生成一个类图并将其保存到磁盘
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

FAQ

Claude desktop 不是已经通过 canvas 支持 mermaid 了吗？

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

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

Cursor 尚不支持响应中的内联图像。

发布

此项目使用 GitHub Actions 自动执行发布到 npm 的过程。

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

1. 确保所有更改都已提交并推送
2. 使用特定版本号或语义版本增量运行发布脚本：

   # 使用特定版本号
   npm run release 0.1.4
   
   # 使用语义版本增量
   npm run release patch  # 增加补丁版本（例如，0.1.3 → 0.1.4）
   npm run release minor  # 增加次要版本（例如，0.1.3 → 0.2.0）
   npm run release major  # 增加主要版本（例如，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  # 使用适当的版本号
   git push origin v0.1.4
   

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

注意：您需要在 GitHub 存储库设置中设置 NPM_TOKEN 密钥。为此：

1. 生成具有发布权限的 npm 访问令牌
2. 转到您的 GitHub 存储库 → 设置 → 密钥和变量 → Actions
3. 创建一个名为 NPM_TOKEN 的新存储库密钥，并将您的 npm 令牌作为值

徽章

<a href="https://glama.ai/mcp/servers/lzjlbitkzr"> <img width="380" height="200" src="https://glama.ai/mcp/servers/lzjlbitkzr/badge" alt="mermaid-mcp-server MCP server" /> </a>

许可证

MIT