美人鱼-MCP服务器

Name: 美人鱼-MCP服务器
Author: peng-shawn

作者：peng-shawn202 星标更新：2025-06-21

安装使用来源：spider==github.com

项目介绍

Mermaid MCP Server

这是一个使用Model Context Protocol (MCP)协议的服务器，用于将Mermaid图表转换为PNG图像或SVG文件。该服务器允许AI助手和其他应用程序通过使用Mermaid Markdown语法从文本描述生成可视化图表。

功能

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

工作原理

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

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

构建

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图表并将它们保存在一个单独的图表文件夹中，解释renderMermaidPng的工作原理"创建的。

使用检查器运行

为了测试和调试，可以使用检查器运行服务器：

npx @modelcontextprotocol/inspector node dist/index.js

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

了解更多关于检查器的信息，请参阅这里。

通过Smithery安装

要自动通过Smithery为Claude Desktop安装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图像或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参数

示例

基本用法

// 使用默认设置生成流程图
{
  "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时）

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

生成SVG输出

// 生成状态图作为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：使用发布脚本（推荐）

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

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

# 使用特定版本号
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存储库 → 设置 → 秘密和变量 → 动作
创建一个名为NPM_TOKEN的新仓库秘密，值为您的npm令牌

徽章

许可证

MIT