mermkit — Mermaid rendering for terminals, chats, and CI

Why use it?

Mermaid only renders natively in a browser. mermkit bridges every other environment.

📄

Terminal-native

See diagrams directly in your terminal via inline images (Kitty, iTerm2, WezTerm) or ASCII fallback — no browser needed.

💬

Chat-ready

Post rendered previews to Slack, Discord, or GitHub. Adapters handle base64 encoding and platform-specific payload shape for you.

🔔

Build artifacts

Generate diagram images as part of your build. If the source didn't change, the output file doesn't change.

🤖

Agent-friendly

Give AI agents a rendering tool they can call via JSON IPC, batch requests, OpenAI tool schemas, or MCP.

Features

Everything you need to turn Mermaid source into usable artifacts.

Multi-engine rendering

Pluggable engine registry. Use embedded, mmdc, ascii, or register your own.

Four output formats

SVG, PNG, PDF, and ASCII. Pick the right format for your environment.

Terminal-native

Inline image protocols (Kitty, iTerm2, WezTerm) with automatic ASCII/Unicode fallback.

Chat-ready adapters

Format rendered diagrams for Slack, Discord, and GitHub in one call.

Agent-friendly

JSON IPC server, batch rendering, OpenAI tool schemas, and an MCP server over stdio.

Multilingual bindings

First-class wrappers for Python, Go, and Rust. Each one spawns serve under the hood.

Examples

Get started in three lines.

# Render a diagram to SVG
mermkit render --in diagram.mmd --out diagram.svg

# Render from stdin to PNG
echo "graph TD; A-->B" | mermkit render --stdin --format png --out out.png

# ASCII output in the terminal
mermkit render --in diagram.mmd --format ascii

from mermkit import MermkitClient

client = MermkitClient()
client.start()
result = client.render("graph TD; A-->B", format="svg")
client.close()

import { render } from "@mermkit/render";

const result = await render(
  { id: "my-diagram", source: "graph TD; A-->B" },
  { format: "svg" }
);
// result.bytes — Uint8Array of SVG

Install

Choose your package manager.

npm

npm install -g @mermkit/cli@latest

npx

npx @mermkit/cli@latest render --in diagram.mmd --out diagram.svg

pip

pip install mermkit

cargo

cargo install mermkit

MCP setup

Expose mermkit as an MCP server over stdio. Use the latest CLI version.

command

npx -y @mermkit/cli@latest mcp

MCP host config

{
  "mcpServers": {
    "mermkit": {
      "command": "npx",
      "args": ["-y", "@mermkit/cli@latest", "mcp"]
    }
  }
}

tool names

mermkit_render
mermkit_renderBatch
mermkit_extract
mermkit_term
mermkit_schema

data URI option

{
  "options": {
    "includeDataUri": true
  }
}

Rendering engines

mermkit is engine-agnostic. It tries engines in priority order when set to auto.

Engine	What it uses	Formats	Notes
`embedded` (default)	`mermaid` + `jsdom`, in-process	SVG, PNG, PDF	Scale option not yet implemented
`mmdc`	`@mermaid-js/mermaid-cli` subprocess	SVG, PNG, PDF	Set `MERMKIT_MMDC_PATH` for a custom binary
`ascii`	Custom TypeScript renderer	ASCII text	Flowcharts and sequence diagrams; skipped in `auto` mode
`stub`	Placeholder	SVG	Test double only — returns source as text, not a real diagram