mermaid-render-mcp

mermaid-mcp

An MCP server that renders Mermaid diagrams to PNG, SVG, or PDF — or converts them to editable draw.io files. Give your LLM the ability to turn diagram syntax into actual images and documents.

Quick start

Claude Code

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

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "mermaid-render-mcp"]
    }
  }
}

Note: the first run downloads headless Chromium (~150 MB), so the initial startup takes a few minutes. If you only need flowcharts and can work with editable files, the drawio fast path skips Chromium entirely.

Docker

No Node.js or Chromium download needed — the image ships with everything (including CJK fonts for Japanese/Chinese/Korean labels):

claude mcp add mermaid -- docker run -i --rm tcinebula/mermaid-render-mcp

To use output_path, mount a host directory and write into it:

{
  "mcpServers": {
    "mermaid": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "C:\\diagrams:/out", "tcinebula/mermaid-render-mcp"]
    }
  }
}

Then pass output_path: "/out/figure.pdf" and the file appears in C:\diagrams.

Remote / self-hosted (HTTP)

The same server speaks Streamable HTTP when PORT is set (or MCP_TRANSPORT=http), so it can be deployed to any container host — Railway, Fly.io, etc. — straight from the Dockerfile:

• Endpoint: POST /mcp (health check at /healthz)
• Set AUTH_TOKEN to require Authorization: Bearer <token>
• output_path is disabled in HTTP mode; base64/XML responses only

From source

git clone https://github.com/tci-nebula/mermaid-mcp.git
cd mermaid-mcp
npm install
claude mcp add mermaid -- node /path/to/mermaid-mcp/server.js

Tool: render_diagram

Parameter	Type	Default	Description
syntax	string	(required)	Mermaid diagram definition
format	png | svg | pdf | drawio	png	Output format (drawio = editable draw.io XML, flowcharts only)
theme	default | dark | neutral | forest	default	Visual theme
background	string	white	CSS colour or transparent
width	number	1200	Canvas width in px (PNG only)
pdfFit	boolean	true	Scale the PDF page to fit the diagram (PDF only)
output_path	string	—	Write the result to this file path instead of returning base64

Returns the rendered image as base64-encoded data so MCP clients can display it inline — or, with output_path, writes the file to disk (handy for PDFs destined for printing or formal document submission).

Example

Ask your LLM:

"Draw me a flowchart of the OAuth login flow"

It generates the Mermaid syntax, calls render_diagram, and you get back a PNG.

The drawio fast path (no Chromium)

format: "drawio" is the one output that never touches a browser. It's pure JavaScript — parse, lay out with dagre, emit XML — so there's no Chromium download, no ~150 MB install, and no multi-minute first run. Conversion is effectively instant.

Reach for it when:

• you want the diagram editable rather than flat — every shape stays a real draw.io object
• you're on a constrained box (CI, a slim container, a locked-down laptop) where downloading Chromium isn't practical
• you just want the diagram now and don't need a raster image

{
  "syntax": "flowchart TD\n  A[Start] --> B{OK?}\n  B -->|yes| C[Ship]\n  B -->|no| A",
  "format": "drawio",
  "output_path": "flow.drawio"
}

Open the result in draw.io (or the VS Code extension) and export to PNG/SVG/PDF from there if you do need an image — that's a complete Chromium-free round trip.

Limits

• Flowcharts only. flowchart and graph diagrams convert; sequence, class, state, ER, and gantt throw an error. Use PNG/SVG/PDF for those.
• theme, background, and width are ignored. Styling is draw.io's job once the file is open.
• Node sizes are estimated from label length, not measured font metrics. draw.io re-measures text when it opens the file so boxes settle correctly — but treat the raw XML geometry as approximate.

Supported syntax: directions TD / TB / BT / LR / RL; shapes [rect], (rounded), {rhombus}, ((circle)), ([stadium]), [[subroutine]], [(cylinder)], {{hexagon}}; edges -->, ---, -.->, ==>, <-->, each optionally carrying a |label|.

How it works

PNG, SVG, and PDF rendering shells out to @mermaid-js/mermaid-cli (bundled as a dependency), which uses a headless Chromium to render diagrams. First npm install downloads Chromium (~150 MB), so it takes a few minutes.

draw.io export is pure JavaScript — a flowchart parser plus dagre layout (the same engine Mermaid uses) emit native mxGraphModel XML, so every shape stays individually editable in draw.io.

Requirements

• Node.js 18+

Roadmap

• PDF export (formal/legal document workflows)
• draw.io XML export (editable diagrams — flowcharts)
• npm package (mermaid-render-mcp)
• Remote-hosted server option (Streamable HTTP transport)

License

MIT