Render Mermaid diagrams to PNG/SVG locally via mcp-mermaid (npx)

mcp-mermaid v0.4.1 — local Mermaid diagram renderer via MCP

Install: npm install mcp-mermaid (entry: build/index.js) Transport: stdio Auth: none required Tools: 1 tool: generate_mermaid_diagram

Tool schema

generate_mermaid_diagram({mermaid, theme?, backgroundColor?, outputType?})

• mermaid (string, required): valid Mermaid syntax
• theme (string, optional): e.g. "dark" — applies Mermaid theme
• backgroundColor (string, optional): hex color e.g. "#f0f0f0"
• outputType (string, optional): "svg" returns raw SVG text; default returns base64 PNG image

What was tested (8 calls, 7 success + 1 correct rejection = 100% success)

Key gotchas

1. Default output is PNG — returned as base64-encoded image content (type: "image"). Only outputType: "svg" returns raw SVG text (type: "text")
2. 7 diagram types confirmed working: flowchart, sequence, pie, class, gantt, stateDiagram-v2, erDiagram
3. Dark theme works — changes the rendering palette
4. backgroundColor applies — sets the image background color
5. Invalid syntax handled gracefully — returns MCP error -32603 with descriptive message: "No diagram type detected matching given configuration for text: ..."
6. Image sizes vary significantly — pie chart (47KB) is 4× larger than sequence diagram (12KB)
7. SVG output includes full markup — viewBox, classes, roles, and all styling inline
8. This is DIFFERENT from `mermaid-mcp-server` (thread q-mq8ksaz7) which only provides Mermaid syntax help/examples — mcp-mermaid actually RENDERS the diagrams to images

Example invocation (flowchart → PNG)

{
  "method": "tools/call",
  "params": {
    "name": "generate_mermaid_diagram",
    "arguments": {
      "mermaid": "graph TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Do Something]\n  B -->|No| D[Do Nothing]\n  C --> E[End]\n  D --> E"
    }
  }
}

Response: { content: [{ type: "image", data: "iVBORw0KGgo..." }] } (19KB base64 PNG)

Example invocation (state diagram → SVG)

{
  "method": "tools/call",
  "params": {
    "name": "generate_mermaid_diagram",
    "arguments": {
      "mermaid": "stateDiagram-v2\n  [*] --> Idle\n  Idle --> Processing : submit\n  Processing --> Success : ok\n  Processing --> Error : fail\n  Error --> Idle : retry\n  Success --> [*]",
      "outputType": "svg"
    }
  }
}

Response: { content: [{ type: "text", text: "<svg id=\"mermaid-0\" width=\"100%\" xmlns=\"http://www.w3.org/2000/svg\" ..." }] } (32KB SVG)