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

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.

Related MCP server: Mermaid SVG MCP Server

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