mermaid-mcp

mermaid-mcp

An MCP server that renders Mermaid diagram markup to PNG images, using @mermaid-js/mermaid-cli (Puppeteer/Chromium) under the hood.

Give it AI-generated Mermaid — flowcharts, sequence, class, ER, gantt, state diagrams — and get back a rendered image, returned inline so the host can preview it and/or written to a file on disk.

Tool

render_mermaid

| Parameter | Type | Required | Description | | ----------------- | -------- | -------- | ----------- | | diagram | string | yes | Mermaid diagram source, e.g. graph TD; A-->B; | | outputPath | string | no | Absolute path ending in .png to also save the image to. Omit to only return inline. | | theme | enum | no | default \| dark \| forest \| neutral (default default) | | backgroundColor | string | no | e.g. white, transparent, #ffffff (default white) | | width | number | no | Output width in pixels | | height | number | no | Output height in pixels | | scale | number | no | Device scale factor; higher = sharper/larger PNG (default 1) |

Returns a short text summary plus the PNG as inline MCP image content. When outputPath is supplied, the file is written there and the path is included in the summary.

Install & build

npm install
npm run build

Browser requirement

Mermaid renders inside a real browser (it needs a DOM for layout), so Google Chrome / Chromium is required. Puppeteer resolves it, in this order:

1. PUPPETEER_EXECUTABLE_PATH — an explicit Chrome/Chromium binary you point it at.
2. Puppeteer's bundled Chromium — downloaded by @mermaid-js/mermaid-cli during npm install.
3. A system-installed Google Chrome — used as a fallback (channel: "chrome") if the bundled

browser can't be launched.

If none can be launched, the tool returns an actionable error: install Chrome, run npx puppeteer browsers install chrome, or set PUPPETEER_EXECUTABLE_PATH.

If Puppeteer's automatic Chromium download is blocked (a locked-down network, or — on some Windows machines — a stalled extraction), just install Google Chrome and the renderer falls back to it.

Test

npm test

Integration tests using Node's built-in test runner (node:test). They exercise the renderer (input validation, inline render, render-to-file) and a full MCP stdio round-trip (spawn the server, list tools, call render_mermaid). The render tests launch headless Chromium, so they need the Chromium install above and take a few seconds each.

Configure in an MCP client

After npm run build, point your MCP client at the built entry over stdio.

Claude Code

# From a local build:
claude mcp add mermaid -- node /absolute/path/to/mermaid-mcp/dist/index.js

# Or from the published package:
claude mcp add mermaid -- npx -y @volare-consulting/mermaid-mcp

Claude Desktop / generic mcpServers config

{
  "mcpServers": {
    "mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/mermaid-mcp/dist/index.js"]
    }
  }
}

Development

npm run dev     # run the server from TypeScript source via tsx

Releasing

Published to the public npm registry as @volare-consulting/mermaid-mcp via a tag-driven GitHub Actions release (.github/workflows/publish.yml), which calls the org's shared publish-npm-public reusable workflow.

1. Bump version in package.json on a PR and merge to main.
2. Tag the merge commit and push the tag:

   git tag v0.1.0 && git push origin v0.1.0

The tag must equal the package.json version or the job fails. Pushing a v* tag builds and publishes the package (tests are skipped — they need headless Chromium the publish runner doesn't provide). Authentication uses the org-level NPM_TOKEN secret.

License

MIT