/ 目錄 / 演練場 / mcp-mermaid
● 社群 hustcc ⚡ 即開即用

mcp-mermaid

作者 hustcc · hustcc/mcp-mermaid

直接在對話中產生經過驗證的 Mermaid 圖表,支援 SVG、PNG 或託管網址,無需另外安裝渲染器。

mcp-mermaid 可動態產生 Mermaid 圖表,並以 base64、SVG 文字、儲存檔案或託管網址的形式回傳。內建語法驗證與多輪自動修正,能自動修復格式錯誤的 Mermaid 語法。也支援資訊圖表(時間軸、比較圖、流程圖)。

為什麼要用

核心特性

即時演示

實際使用效果

mermaid.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示,然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mermaid",
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mermaid": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-mermaid"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add mermaid -- npx -y mcp-mermaid

一行命令搞定。用 claude mcp list 驗證,claude mcp remove 移除。

使用場景

實戰用法: mcp-mermaid

根據文字描述產生系統架構圖

👤 撰寫設計文件的工程師 ⏱ ~10 min beginner

何時使用: 已在文件中描述了一套架構,想在不離開對話的情況下產生圖表。

前置條件
  • 已安裝 mcp-mermaid — 在 MCP 客戶端設定中執行 npx -y mcp-mermaid
步驟
  1. 描述系統架構
    以下是我的架構:Cloudflare → API (Node) → Postgres + Redis → Worker (Go)。請產生一張 Mermaid 流程圖來呈現這個架構。✓ 已複製
    → 產生有效的 Mermaid 原始碼並渲染為 SVG
  2. 調整樣式
    將 Cloudflare 改為藍色、Postgres 改為綠色、Redis 改為紅色,並對非同步的連線使用虛線箭頭。✓ 已複製
    → 輸出修改後的圖表
  3. 儲存為檔案
    以白色背景將圖表輸出為 PNG 檔案,儲存至 ./docs/arch.png。✓ 已複製
    → 檔案已儲存至磁碟

結果: 產生一張可直接放入設計文件的架構 PNG 圖。

注意事項
  • 過於複雜的圖表會超過 Mermaid 的版面配置限制 — 拆分成多張圖表,或改用 subgraph 分組
  • 主題顏色與文件風格不符 — 明確傳入 theme 設定,不要依賴預設值
搭配使用: filesystem

在錯誤回報中加入時序圖

👤 提報競態條件等複雜錯誤的工程師 ⏱ ~5 min beginner

何時使用: 用文字描述誰在什麼時間呼叫了誰,讀起來很難理解。

步驟
  1. 描述執行時序
    客戶端發送 POST,API 開始交易並寫入資料庫,但在提交前崩潰。與此同時,客戶端又發出一次重試請求。請畫出這個時序圖。✓ 已複製
    → 清楚呈現平行生命線的時序圖
  2. 嵌入 Issue 中
    請給我 Mermaid 原始碼,讓我可以直接貼到 GitHub Issue(GitHub 原生支援 Mermaid 渲染)。✓ 已複製
    → 可直接貼上的原始碼

結果: 讓審查者 10 秒內就能看懂的錯誤回報。

搭配使用: github

根據時間規劃產生專案甘特圖

👤 不想為一次性需求購買甘特圖軟體的專案負責人 ⏱ ~5 min beginner

何時使用: 需要為 PRD 或啟動會議臨時製作時間軸。

步驟
  1. 列出各階段
    各階段如下:探索(2 週)、設計(3 週)、實作(6 週)、QA(2 週,與實作最後 2 週重疊)。起始日期為 2026-05-01,請產生甘特圖。✓ 已複製
    → 產生有效的甘特圖原始碼
  2. 輸出 PNG
    請儲存為 PNG 檔案,並給我可嵌入 PRD 的託管網址。✓ 已複製
    → PNG 檔案路徑及託管網址

結果: 在一分鐘內產生可用於 PRD 的時間軸圖表。

組合

與其他 MCP 搭配,撬動十倍槓桿

mermaid + filesystem

將產生的圖表儲存為有版本管理的資產檔案

產生第二版架構圖,儲存為 ./docs/arch-v2.png,並更新 ./docs/README.md 中的參照連結。✓ 已複製
mermaid + github

將 Mermaid 原始碼放入 PR 描述中,GitHub 會原生渲染

撰寫一份說明資料流變更的 PR 描述,並在內文中嵌入 Mermaid 時序圖。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
generate_mermaid source: str (Mermaid DSL), output: base64|svg|mermaid|file|svgUrl|pngUrl, theme?, backgroundColor? 任何圖表產生需求 free (local render) or 1 API call for hosted URLs
validate_mermaid source: str 若對語法不確定,可在呼叫 generate 前先行驗證 free

成本與限制

運行它的成本

API 配額
本地渲染免費;託管網址輸出使用 mermaid.ink,合理使用範圍內免費
每次呼叫 Token 數
極少——圖表 DSL 語法簡潔
費用
免費
提示
若目標平台(如 GitHub、文件系統)原生支援渲染,優先選用 'mermaid' 格式輸出;僅在需要伺服器端渲染時才使用 PNG/SVG。

安全

權限、密鑰、影響範圍

憑證儲存:
資料出站: base64/svg 使用本地渲染;託管網址使用 mermaid.ink

故障排查

常見錯誤與修復

Mermaid parse error

LLM 產生了無效的 DSL 語法。請先透過 validate_mermaid 進行驗證;mcp-mermaid 也會在第二輪自動嘗試修正。

驗證: validate_mermaid on the source
PNG output fails in Docker

PNG 渲染需要無頭瀏覽器環境;請使用已內建無頭瀏覽器的官方 Docker 映像檔。

驗證: docker run hustcc/mcp-mermaid
Diagram too big, gets cut off

將圖表拆分為多個 subgraph,或分成多張獨立圖表。

替代方案

mcp-mermaid 對比其他方案

替代方案何時用它替代權衡
PlantUML MCP偏好 PlantUML 更完整的 UML 語法支援需要 Java 執行環境
antv-chart / mcp-server-chart需要資料圖表多於架構圖輸出形式不同
Raw Mermaid via the web editor不在對話式工作流程中使用無 MCP 整合

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills