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 `
• `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`

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

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

License

MIT