mermaid-render

Render Mermaid diagrams to SVG, PNG, PDF, or editable, connected Visio VSDX on Linux, Windows, and macOS. Uses the official Mermaid.js renderer; no Node.js or Microsoft Visio installation is required. Python 3.10+ is supported.

Install from PyPI

Install the command-line tool with uv:

uv tool install mermaid-render

Mermaid.js and Chromium support files install automatically on the first render. To prepare them in advance, run mermaid-render setup.

Command-line usage

mermaid-render diagram.mmd                  # Creates diagram.svg
mermaid-render diagram.mmd -o diagram.png   # PNG at scale 2 (192 dpi)
mermaid-render diagram.mmd -o diagram.pdf
mermaid-render diagram.mmd -o diagram.vsdx

The output extension selects the format; use --format to select it explicitly. SVG is the default. The default theme is redux-color; use --theme to change it.

• PNG: Defaults to twice the SVG's pixel dimensions. Use --scale 1 for 96 dpi, or --background transparent for a transparent background.
• PDF: A single diagram-sized vector page. Scale applies only to PNG.
• VSDX: Flowcharts, sequence diagrams, and state diagrams, with editable shapes and glued connectors. Flowchart subgraphs become native Visio containers with member relationships, including nested subgraphs and internal connectors. Flowcharts and state diagrams default to right-angle connectors; choose --visio-connectors straight or --visio-connectors mermaid for direct lines or detailed Mermaid curves. Mermaid attachment positions, standard shape connection points, and rendered border widths are retained.

Sequence diagrams preserve participants and actors, lifelines, nested activations, message labels and numbering, notes, interaction frames, and participant creation/destruction. Each participant's artwork forms one movable group, with messages attached at their chronological positions. Messages use straight lines and simple rectangular self-loops; --visio-connectors applies to flowcharts and state diagrams. Try examples/sequence.mmd:

mermaid-render examples/sequence.mmd -o sequence.vsdx

State diagrams preserve initial/final symbols, choices, fork/join bars, labeled transitions and self-loops, multiline descriptions, notes, and nested or concurrent states. Composite states become native Visio containers, and transitions remain glued to editable shapes. Try examples/state.mmd:

mermaid-render examples/state.mmd -o state.vsdx

Other Mermaid diagram types currently support SVG, PNG, and PDF output.

Python usage

Install into your project with uv add mermaid-render, or into an existing environment with uv pip install mermaid-render.

from mermaid_render import convert

source = """flowchart LR
    A[Input] --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Reject]
"""

convert(source, "diagram.svg")
convert(source, "diagram.png", background="transparent")  # scale=2 by default
convert(source, "diagram.pdf")
convert(source, "diagram.vsdx", visio_connectors="right-angle")
svg_bytes = convert(source)  # Without an output path, returns SVG bytes

convert returns bytes for every format and writes them when an output path is supplied. Use theme=, scale=, and background= to customize rendering.

MCP server

Install optional MCP support:

uv tool install --upgrade 'mermaid-render[mcp]'

Add the stdio server to your MCP client's configuration:

{
  "mcpServers": {
    "mermaid-render": {
      "command": "mermaid-render-mcp"
    }
  }
}

The server provides one tool, render_mermaid. Supply either Mermaid source or an input_path ending in .mmd/.mermaid, plus an output_path:

{
  "source": "flowchart LR; A[Input] -->|Process| B[Output]",
  "output_path": "/absolute/path/diagram.svg"
}

The output extension selects SVG, PNG, PDF, or VSDX. Without an extension, the server appends .svg; an explicit format overrides the default and must match any supplied extension. The result contains the absolute output_path, format, and mime_type. Existing output is replaced only after rendering succeeds. Use absolute paths: relative paths resolve from the server's working directory.

Optional arguments are theme, title, background, scale, and visio_connectors, with the same defaults as the Python API. Runtime setup is automatic. For offline use, install a bundled wheel with its mcp extra and the MCP dependencies available in your environment.

Runtime support files

Support files persist in user application data, rather than a temporary cache:

The package checks version-matched user support files first, then bundled files. Setup copies bundled files into the support directory when needed, or downloads missing files. Existing valid files are reused. Paths are managed automatically.

On Linux, Chromium also needs system libraries. On a connected machine, install them with:

uvx --from playwright==1.63.0 playwright install-deps chromium

Install in an offline environment

Download a bundled wheel from GitHub Releases, matching the target operating system and architecture:

Transfer the wheel to the target machine and install it using its full filename, for example:

uv tool install ./mermaid_render-0.11.0-py3-none-macosx_13_0_arm64.whl
mermaid-render diagram.mmd -o diagram.vsdx

Bundled wheels include Mermaid.js and Chromium, so rendering requires no runtime downloads. Optional mermaid-render setup copies these assets into the user support directory.

Linux wheels are tested on Ubuntu 24.04 and require compatible system browser libraries to be present on the offline machine. They are not manylinux wheels. macOS wheels encode the minimum OS version required by their binaries; CI tests on macOS 15.

GitHub Releases also contain the lightweight PyPI wheel and source archive. Choose a platform-specific wheel for the bundled runtime.

Contribute

Clone the repository and use uv to install dependencies and run tests:

git clone https://github.com/himbeles/mermaid-render.git
cd mermaid-render
uv sync --locked
uv run pytest -q
uv run mermaid-render examples/example.mmd -o diagram.vsdx

Rendering and browser tests automatically prepare missing support files. On Linux, install browser system libraries first with uv run python -m playwright install-deps chromium.

The rendering API lives in src/mermaid_render/api.py; connected VSDX generation in semantic.py (flowcharts and state diagrams) and sequence.py; Mermaid semantics and artwork capture in the *_capture.js files and capture.js; runtime installation in assets.py. Add regression tests for rendering or connector changes. Visual checks in an independent VSDX viewer are useful alongside automated tests.

Build and release

Build lightweight PyPI distributions:

uv build --out-dir dist/pypi
uv run python scripts/check_lightweight_dist.py dist/pypi

Build and test a bundled wheel on its target OS/architecture:

uv run python scripts/build_platform_wheel.py --outdir dist/bundled
uv run python scripts/test_wheel_install.py dist/bundled/*.whl

GitHub Actions builds and tests lightweight distributions plus four platform-specific wheels. To release, update project.version in pyproject.toml, run uv lock, commit, and push a matching v<version> tag. The workflow publishes lightweight distributions to PyPI through Trusted Publishing and attaches all distributions to GitHub Releases. Main-branch pushes, pull requests, and manual runs build without publishing.

License

MIT; see LICENSE.

Originally adapted from Freddy Beltran's mermaid-to-visio project. SVG capture and low-level VSDX generation retain that heritage; connected flowchart, sequence-diagram, and state-diagram export were developed further in mermaid-render.

Bundled Mermaid, Chromium, and Playwright retain their upstream licenses and notices.