{
  "markdown": "# mermaid-mcp\n\n[![test](https://github.com/tci-nebula/mermaid-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/tci-nebula/mermaid-mcp/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/mermaid-render-mcp)](https://www.npmjs.com/package/mermaid-render-mcp)\n\nAn [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.\n\n## Quick start\n\n### Claude Code\n\n```bash\nclaude mcp add mermaid -- npx -y mermaid-render-mcp\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mermaid\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mermaid-render-mcp\"]\n    }\n  }\n}\n```\n\n> **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.\n\n### Docker\n\nNo Node.js or Chromium download needed — the image ships with everything (including CJK fonts for Japanese/Chinese/Korean labels):\n\n```bash\nclaude mcp add mermaid -- docker run -i --rm tcinebula/mermaid-render-mcp\n```\n\nTo use `output_path`, mount a host directory and write into it:\n\n```json\n{\n  \"mcpServers\": {\n    \"mermaid\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-v\", \"C:\\\\diagrams:/out\", \"tcinebula/mermaid-render-mcp\"]\n    }\n  }\n}\n```\n\nThen pass `output_path: \"/out/figure.pdf\"` and the file appears in `C:\\diagrams`.\n\n### Remote / self-hosted (HTTP)\n\nThe 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:\n\n- Endpoint: `POST /mcp` (health check at `/healthz`)\n- Set `AUTH_TOKEN` to require `Authorization: Bearer <token>`\n- `output_path` is disabled in HTTP mode; base64/XML responses only\n\n### From source\n\n```bash\ngit clone https://github.com/tci-nebula/mermaid-mcp.git\ncd mermaid-mcp\nnpm install\nclaude mcp add mermaid -- node /path/to/mermaid-mcp/server.js\n```\n\n## Tool: `render_diagram`\n\n| Parameter | Type | Default | Description |\n|---|---|---|---|\n| `syntax` | string | *(required)* | Mermaid diagram definition |\n| `format` | `png` \\| `svg` \\| `pdf` \\| `drawio` | `png` | Output format (`drawio` = editable draw.io XML, flowcharts only) |\n| `theme` | `default` \\| `dark` \\| `neutral` \\| `forest` | `default` | Visual theme |\n| `background` | string | `white` | CSS colour or `transparent` |\n| `width` | number | `1200` | Canvas width in px (PNG only) |\n| `pdfFit` | boolean | `true` | Scale the PDF page to fit the diagram (PDF only) |\n| `output_path` | string | — | Write the result to this file path instead of returning base64 |\n\nReturns 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).\n\n### Example\n\nAsk your LLM:\n\n> \"Draw me a flowchart of the OAuth login flow\"\n\nIt generates the Mermaid syntax, calls `render_diagram`, and you get back a PNG.\n\n## The `drawio` fast path (no Chromium)\n\n`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.\n\nReach for it when:\n\n- you want the diagram **editable** rather than flat — every shape stays a real draw.io object\n- you're on a constrained box (CI, a slim container, a locked-down laptop) where downloading Chromium isn't practical\n- you just want the diagram now and don't need a raster image\n\n```json\n{\n  \"syntax\": \"flowchart TD\\n  A[Start] --> B{OK?}\\n  B -->|yes| C[Ship]\\n  B -->|no| A\",\n  \"format\": \"drawio\",\n  \"output_path\": \"flow.drawio\"\n}\n```\n\nOpen 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.\n\n### Limits\n\n- **Flowcharts only.** `flowchart` and `graph` diagrams convert; sequence, class, state, ER, and gantt throw an error. Use PNG/SVG/PDF for those.\n- **`theme`, `background`, and `width` are ignored.** Styling is draw.io's job once the file is open.\n- **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.\n\nSupported syntax: directions `TD` / `TB` / `BT` / `LR` / `RL`; shapes `[rect]`, `(rounded)`, `{rhombus}`, `((circle))`, `([stadium])`, `[[subroutine]]`, `[(cylinder)]`, `{{hexagon}}`; edges `-->`, `---`, `-.->`, `==>`, `<-->`, each optionally carrying a `|label|`.\n\n## How it works\n\nPNG, 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.\n\ndraw.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.\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) 18+\n\n## Roadmap\n\n- [x] PDF export (formal/legal document workflows)\n- [x] draw.io XML export (editable diagrams — flowcharts)\n- [x] npm package ([`mermaid-render-mcp`](https://www.npmjs.com/package/mermaid-render-mcp))\n- [x] Remote-hosted server option (Streamable HTTP transport)\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 5886,
  "sha": "9741d9d1a376888bd0bfa13f3d242373647f96fe2aa43c70fc6e31e5f3061642",
  "repo_slug": "tci-nebula/mermaid-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tci_nebula_mermaid_render_mcp_500fb878/readme"
}