美人鱼 MCP 服务器

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

特征

• 将美人鱼图代码转换为 PNG 图像

• 支持多种图表主题（默认、森林、深色、中性）

• 可自定义的背景颜色

• 使用 Puppeteer 实现高质量无头浏览器渲染

• 实施 MCP 协议，实现与 AI 助手的无缝集成

• 灵活的输出选项：直接返回图像或保存到磁盘

• 带有详细错误消息的错误处理

Related MCP server: mcp-mermaid-validator

工作原理

服务器使用 Puppeteer 启动无头浏览器，将美人鱼图渲染为 SVG，并截取渲染图的屏幕截图。该过程包括：

1. 启动无头浏览器实例

2. 使用 Mermaid 代码创建 HTML 模板

3. 加载 Mermaid.js 库

4. 将图表渲染为 SVG

5. 将渲染后的 SVG 截图为 PNG

6. 直接返回图像或将其保存到磁盘

建造

npx tsc

用法

与 Claude 桌面一起使用

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

与 Cursor 和 Cline 一起使用

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

您可以在./diagrams下找到美人鱼图列表，它们是使用 Cursor 代理创建的，提示为：“生成美人鱼图并将其保存在单独的图表文件夹中，解释 renderMermaidPng 如何工作”

与检查器一起运行

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

npx @modelcontextprotocol/inspector node dist/index.js

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

在此处了解有关检查员的更多信息。

通过 Smithery 安装

要通过Smithery自动安装 Claude Desktop 的美人鱼图表生成器：

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 ：将美人鱼图代码转换为 PNG 图像

  • 参数：

    • code ：要渲染的美人鱼图代码

    • theme ：（可选）图表主题。选项：“默认”、“森林”、“深色”、“中性”

    • backgroundColor ：（可选）图表的背景颜色，例如“白色”、“透明”、“#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参数

示例

基本用法

// 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
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

常问问题

Claude 桌面不是已经通过画布支持美人鱼了吗？

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

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

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

出版

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

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

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. 该脚本将：

   • 验证版本格式或语义增量

   • 检查你是否在主分支上

   • 检测并警告文件之间的版本不匹配

   • 一致更新所有版本引用（package.json、package-lock.json 和 index.ts）

   • 创建包含所有版本更改的单个提交

   • 创建并推送 git 标签

   • GitHub 工作流程将自动构建并发布到 npm

方法二：手动处理

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 存储库 → 设置 → 机密和变量 → 操作

3. 创建一个名为NPM_TOKEN的新存储库机密，并使用您的 npm 令牌作为值

徽章

执照

麻省理工学院