This MCP server renders Mermaid diagram markup (flowcharts, sequence, class, ER, Gantt, state diagrams, etc.) into PNG images using a headless Chromium browser. It provides a single render_mermaid tool with the following capabilities:
Render & preview: Convert Mermaid source code into a PNG image returned inline for immediate preview.
Save to disk: Optionally save the rendered PNG to a specified absolute file path.
Customize theme: Choose from default, dark, forest, or neutral themes.
Set background color: Use named colors (e.g., white, transparent) or hex codes (e.g., #ffffff).
Control dimensions: Specify custom width and height in pixels.
Adjust scale/resolution: Set a device scale factor for sharper or higher-resolution output.
Renders Mermaid diagram markup (flowcharts, sequence, class, ER, gantt, state diagrams) to PNG images, with options for theme, background color, width, height, and scale.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mermaid-mcp render a sequence diagram for API authentication"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
render_mermaidParameter | Type | Required | Description |
| string | yes | Mermaid diagram source, e.g. |
| string | no | Absolute path ending in |
| enum | no |
|
| string | no | e.g. |
| number | no | Output width in pixels |
| number | no | Output height in pixels |
| number | no | Device scale factor; higher = sharper/larger PNG (default |
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
npm install
npm run buildMermaid renders inside a real browser (it needs a DOM for layout), so Google Chrome / Chromium is required. Puppeteer resolves it, in this order:
PUPPETEER_EXECUTABLE_PATH — an explicit Chrome/Chromium binary you point it at.
Puppeteer's bundled Chromium — downloaded by @mermaid-js/mermaid-cli during npm install.
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.
npm testIntegration 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.
After npm run build, point your MCP client at the built entry over stdio.
# 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-mcpmcpServers config{
"mcpServers": {
"mermaid": {
"command": "node",
"args": ["/absolute/path/to/mermaid-mcp/dist/index.js"]
}
}
}npm run dev # run the server from TypeScript source via tsxPublished 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.
Bump version in package.json on a PR and merge to main.
Tag the merge commit and push the tag:
git tag v0.1.0 && git push origin v0.1.0The 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.
MIT
Render Mermaid diagram markup to a PNG image. Returns the image inline so it can be previewed. If outputPath (an absolute .png path) is provided, the PNG is also saved there and the path is returned. Useful for turning AI-generated Mermaid (flowcharts, sequence, class, ER, gantt, state diagrams, etc.) into images.
| Name | Required | Description | Default |
|---|---|---|---|
| diagram | Yes | Mermaid diagram source, e.g. `graph TD; A-->B;` | |
| outputPath | No | Absolute path ending in .png to save the image to. Omit to only return the image inline. | |
| theme | No | Mermaid theme. Defaults to "default". | |
| backgroundColor | No | Background color, e.g. "white", "transparent", "#ffffff". Defaults to "white". | |
| width | No | Output width in pixels. | |
| height | No | Output height in pixels. | |
| scale | No | Device scale factor; higher = sharper/larger PNG. Defaults to 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors: returns image inline, optionally saves to file if outputPath is provided, and defaults for scale and backgroundColor. However, it does not mention error handling (e.g., invalid diagram syntax, file write failures) or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with core purpose and key behavior, then lists supported diagram types. Every sentence is informative and no word is wasted. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description covers essential aspects (purpose, inline return, optional saving). However, it omits error behavior, prerequisites (e.g., valid Mermaid syntax), and any side effects beyond file writing. Could be more complete for a tool lacking annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline of 3. The description adds minimal extra meaning beyond schema descriptions: it specifies that outputPath must be an absolute .png path and explains scale factor effect. No parameter is left undocumented, but the description does not significantly enrich understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Render...to a PNG image'), specifies the resource (Mermaid diagram markup), and lists supported diagram types (flowcharts, sequence, etc.). It is precise and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is useful for converting Mermaid diagrams to images, which implies when to use it. However, it does not explicitly state when not to use it or provide alternatives. No sibling tools exist for comparison, so the guidance is implicit but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0render_mermaidScored across 1 tool
Only one tool exists, so there is no ambiguity in purpose. The tool clearly renders Mermaid diagrams to PNG.
The tool name 'render_mermaid' follows a clear verb_noun pattern, consistent with the single tool in the set.
A single tool feels thin for a server, but it may be justified if the sole purpose is rendering. It borders on the lower end of acceptable scope.
The tool covers the core rendering functionality across many diagram types. Minor gaps like syntax validation or listing available diagram types are not critical.
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Let Claude, Cursor, or ChatGPT author Mermaid diagrams your team can read and share.
Publish markdown documents as public share links with mermaid diagram support. Built by AutEng.ai
