# Mermaid-MCP 服务器
## 基本信息
- Slug: `peng-shawn-mermaid-mcp-server`
- Source: modelscope
- Publisher: @peng-shawn/mermaid-mcp-server
- Categories: developer-tools / image-and-video-processing
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@peng-shawn/mermaid-mcp-server
## 简介
一个将Mermaid图表转换为PNG图像的模型上下文协议（MCP）服务器。
## 安装提示

```bash
npx tsc
```

## MCP Server 详情

# 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. 直接返回图像或将图像保存到磁盘

## 构建

```bash
npx tsc
```


## 使用

### 与 Claude 桌面版一起使用

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


### 与 Cursor 和 Cline 一起使用

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


你可以在 `./diagrams` 下找到一系列 Mermaid 图表，这些图表是使用 Cursor 代理通过提示 "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work" 生成并保存的。

### 使用检查器运行

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

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```


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

了解更多关于检查器的信息，请访问[这里](https://modelcontextprotocol.io/docs/tools/inspector)。

### 通过 Smithery 安装

要通过 [Smithery](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server) 自动安装 Claude Desktop 的 Mermaid 图表生成器：

```bash
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` 参数

## 示例

### 基本用法

```javascript
// 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]"
}
```


### 使用主题和背景颜色

```javascript
// 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` 时）

```javascript
// 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 桌面版不是已经通过 canvas 支持 mermaid 了吗？

是的，但它不支持 `theme` 和 `backgroundColor` 选项。此外，拥有一个专用服务器使得使用不同的 MCP 客户端创建 mermaid 图表变得更加容易。

### 为什么在与 Cursor 一起使用时需要指定 `CONTENT_IMAGE_SUPPORTED=false`？

Cursor 还不支持在响应中内联图像。

## 发布

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

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

1. 确保所有更改都已提交并推送
2. 使用特定版本号或语义版本增量运行发布脚本：
   ```bash
   # 使用特定版本号
   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. 脚本将执行以下操作：
   - 验证版本格式或语义增量
   - 检查是否位于主分支
   - 检测并警告文件之间的版本不匹配
   - 一致更新所有版本引用（`package.json`、`package-lock.json` 和 `index.ts`）
   - 创建包含所有版本更改的单个提交
   - 创建并推送 git 标签
   - GitHub 工作流将自动构建并发布到 npm

### 方法 2：手动过程

1. 更新你的代码并提交更改
2. 创建并推送带有版本号的新标签：
   ```bash
   git tag v0.1.4  # 使用适当的版本号
   git push origin v0.1.4
   ```
3. GitHub 工作流将自动：
   - 构建项目
   - 根据标签中的版本号发布到 npm

注意：你需要在你的 GitHub 仓库设置中配置 `NPM_TOKEN` 密钥。为此，请执行以下步骤：
1. 生成具有发布权限的 npm 访问令牌
2. 转到你的 GitHub 仓库 → 设置 → 密码和变量 → 操作
3. 创建一个名为 `NPM_TOKEN` 的新仓库密钥，其值为你的 npm 令牌

## 徽章

[![smithery 徽章](https://smithery.ai/badge/@peng-shawn/mermaid-mcp-server)](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server)

<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 服务器" />
</a>

## 许可证

MIT