io.github.tci-nebula/mermaid-render-mcp
Renders Mermaid diagram syntax to PNG or SVG images for LLM clients
Open source Open in the app JSON README (API)
About
Renders Mermaid diagram syntax to PNG or SVG images for LLM clients
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- tci-nebula
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.3.0
- Last push
- 2026-08-20T02:08:00Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:30
- Updated
- 2026-08-29 04:01:30
- Origin id
io.github.tci-nebula/mermaid-render-mcp
README
# mermaid-mcp
[](https://github.com/tci-nebula/mermaid-mcp/actions/workflows/test.yml) [](https://www.npmjs.com/package/mermaid-render-mcp)
An [MCP](https://modelcontextprotocol.io/) server that renders [Mermaid](https://mermaid.js.org/) diagrams to PNG, SVG, or PDF — or converts them to editable [draw.io](https://www.drawio.com/) files. Give your LLM the ability to turn diagram syntax into actual images and documents.
## Quick start
### Claude Code
```bash
claude mcp add mermaid -- npx -y mermaid-render-mcp
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```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](#the-drawio-fast-path-no-chromium) skips Chromium entirely.
### Docker
No Node.js or Chromium download needed — the image ships with everything (including CJK fonts for Japanese/Chinese/Korean labels):
```bash
claude mcp add mermaid -- docker run -i --rm tcinebula/mermaid-render-mcp
```
To use `output_path`, mount a host directory and write into it:
```json
{
"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](https://modelcontextprotocol.io/docs/concepts/transports) 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
```bash
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
```json
{
"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](https://app.diagrams.net/) (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`](https://github.com/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](https://github.com/dagrejs/dagre) layout (the same engine Mermaid uses) emit native mxGraphModel XML, so every shape stays individually editable in draw.io.
## Requirements
- [Node.js](https://nodejs.org/) 18+
## Roadmap
- [x] PDF export (formal/legal document workflows)
- [x] draw.io XML export (editable diagrams — flowcharts)
- [x] npm package ([`mermaid-render-mcp`](https://www.npmjs.com/package/mermaid-render-mcp))
- [x] Remote-hosted server option (Streamable HTTP transport)
## License
[MIT](LICENSE)