mcp-mermaid MCP — 使用场景, 安装 & 实时演示

Name: mcp-mermaid MCP Server
Author: hustcc

为什么要用

核心特性

Full Mermaid syntax support — flowcharts, sequence, class, state, ER, gantt, etc.
Six output formats: base64, SVG text, Mermaid source, PNG file, SVG URL, PNG URL
Built-in syntax validation and multi-round self-correction
Configurable backgroundColor and theme
Docker deploy + SSE/Streamable HTTP transports

实时演示

实际使用效果

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

Generate a system architecture diagram from prose

👤 Engineers writing design docs ⏱ ~10 min beginner

何时使用： You've described an architecture in a doc and want a diagram without leaving chat.

前置条件

mcp-mermaid installed — npx -y mcp-mermaid in your MCP client config

步骤

Describe the system

Here's my architecture: Cloudflare → API (Node) → Postgres + Redis → Worker (Go). Generate a Mermaid flowchart showing this.✓ 已复制

→ Valid Mermaid source rendered as SVG
Iterate on styling

Make Cloudflare blue, Postgres green, Redis red. Use dashed edges for async.✓ 已复制

→ Revised diagram
Save to file

Output as PNG file at ./docs/arch.png with white background.✓ 已复制

→ File on disk

结果： An architecture PNG you can drop into the design doc.

注意事项

Very complex diagrams hit Mermaid's layout limits — Break into multiple diagrams, or switch to subgraph grouping
Theme colors don't match your doc — Pass theme config explicitly rather than relying on defaults

搭配使用： filesystem

Draft a sequence diagram in a bug report

👤 Engineers filing tricky race-condition bugs ⏱ ~5 min beginner

何时使用： Prose description of who calls whom when is hard to read.

步骤

Describe the sequence

Client sends POST, API starts transaction, writes to DB, crashes before commit. Meanwhile a retry comes in from the client. Draw a sequence diagram.✓ 已复制

→ Clear sequence with parallel lifelines
Inline into issue

Give me the Mermaid source so I can paste into a GitHub issue (which renders Mermaid natively).✓ 已复制

→ Source ready to paste

结果： A bug report reviewers can grok in 10 seconds.

搭配使用： github

Generate a project Gantt from a timeline

👤 Project leads who don't want to pay for gantt software for a one-off ⏱ ~5 min beginner

何时使用： Ad-hoc timeline for a PRD or kickoff.

步骤

List phases

Phases: Discovery (2 weeks), Design (3 weeks), Implementation (6 weeks), QA (2 weeks overlap with impl last 2 weeks). Starting 2026-05-01. Make a gantt.✓ 已复制

→ Valid Gantt source
Output PNG

Save as PNG and also give me the URL I can embed in the PRD.✓ 已复制

→ PNG path + hosted URL

结果： A timeline graphic for your PRD in under a minute.

组合

与其他 MCP 搭配，撬动十倍杠杆

mermaid + filesystem

Save generated diagrams as versioned assets

Generate architecture diagram v2 as ./docs/arch-v2.png and update the reference in ./docs/README.md.✓ 已复制

mermaid + github

Put Mermaid source in a PR description — GitHub renders it natively

Draft a PR description explaining the data flow change, include a Mermaid sequence diagram inline.✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
generate_mermaid	source: str (Mermaid DSL), output: base64\|svg\|mermaid\|file\|svgUrl\|pngUrl, theme?, backgroundColor?	Any diagram generation	free (local render) or 1 API call for hosted URLs
validate_mermaid	source: str	Before generate if you're unsure about syntax	free

成本与限制

运行它的成本

API 配额: Local rendering is free; hosted URL output uses mermaid.ink which is free with reasonable use
每次调用 Token 数: Small — diagram DSL is compact
费用: Free
提示: Prefer 'mermaid' output for GitHub/docs that render natively; only go to PNG/SVG when rendering server-side is needed.

安全

权限、密钥、影响范围

凭据存储： None

数据出站： Local render for base64/svg; mermaid.ink for hosted URLs

Hosted URLs (mermaid.ink) expose your diagram content — don't use for confidential system diagrams.
PNG rendering spawns a headless browser — make sure it's not exposed on the public internet.

故障排查

常见错误与修复

Mermaid parse error

The LLM emitted invalid DSL. Validate via validate_mermaid first; mcp-mermaid also self-corrects on second pass.

验证： validate_mermaid on the source

PNG output fails in Docker

The image needs a headless browser; use the official Docker image which bundles it.

验证： docker run hustcc/mcp-mermaid

Diagram too big, gets cut off

Break into subgraphs or split into multiple diagrams.

替代方案

mcp-mermaid 对比其他方案

替代方案	何时用它替代	权衡
PlantUML MCP	You prefer PlantUML's deeper UML surface	Requires Java runtime
antv-chart / mcp-server-chart	You need data charts more than diagrams	Different shape of output
Raw Mermaid via the web editor	You're not in a chat workflow	No MCP integration

mcp-mermaid