Mermaid MCP 服务器

这是一个实现模型上下文协议（MCP）的服务器，能够将Mermaid图表转换为PNG图像。该服务器允许AI助手和其他应用程序使用Mermaid的Markdown语法从文本描述生成可视化图表。

功能特性

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

工作原理

服务器使用Puppeteer启动一个无头浏览器实例，将Mermaid图表渲染为SVG格式，然后截取渲染后图表的屏幕截图。整个过程包括：

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

构建

npx tsc

使用方法

与Claude桌面版配合使用

"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代理通过提示"生成Mermaid图表并将它们保存在单独的diagrams文件夹中，解释renderMermaidPng的工作原理"创建的。

使用检查器运行

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

npx @modelcontextprotocol/inspector node dist/index.js

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

了解更多关于检查器的信息请点击这里。

通过Smithery安装

要通过Smithery自动为Claude桌面版安装Mermaid图表生成器：

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

Docker和Smithery环境

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

服务器现在默认尝试使用Puppeteer捆绑的浏览器
如果遇到与浏览器相关的错误，您有两个选择：

选项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[开始] --> B{是吗?}\n    B -->|是| C[好的]\n    B -->|否| D[结束]"
}

使用主题和背景颜色

// 使用森林主题和浅灰色背景生成序列图
{
  "code": "sequenceDiagram\n    Alice->>John: 你好John，你好吗?\n    John-->>Alice: 很好!",
  "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"
}

常见问题

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

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

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

Cursor目前还不支持在响应中包含内联图像。

发布

该项目使用GitHub Actions自动化发布到npm的过程。

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

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

使用特定版本号或语义版本增量运行发布脚本：

# 使用特定版本号
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）

脚本将：
- 验证版本格式或语义增量
- 检查是否位于主分支
- 检测并警告文件之间的版本不匹配
- 一致地更新所有版本引用（package.json、package-lock.json和index.ts）
- 创建包含所有版本更改的单一提交
- 创建并推送git标签
- GitHub工作流将自动构建并发布到npm

方法2：手动过程

更新代码并提交更改

创建并推送带有版本号的新标签：

git tag v0.1.4  # 使用适当的版本号
git push origin v0.1.4

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

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

生成具有发布权限的npm访问令牌
转到您的GitHub仓库 → 设置 → Secrets and variables → Actions
创建一个名为NPM_TOKEN的新仓库密钥，并将您的npm令牌作为值

徽章

许可证

MIT