Agentic Mermaid

Official8 toolsLive

by adewale · TypeScript

Render, verify, describe, and safely edit Mermaid diagrams through MCP.

Topics

mcpmermaidmermaid-alternativemermaid-diagrams

Captured live from the server via tools/list.

execute

Run synchronous JavaScript against the mermaid SDK in an isolated sandbox. Code runs as an expression or statement body — return the final value. Promise jobs, async/await, and dynamic import are not supported. Multi-step diagram edits should be one execute() call. The SDK declaration is TypeScript-shaped for guidance; the sandbox does not transpile type annotations. Hosted note: execute runs in an on-demand isolate and costs more than the direct render_svg/render_ascii/render_png/verify/describe tools — prefer those for plain render/verify calls. For straightforward structured edits, prefer the declarative mutate/build tools; reserve execute for logic the ops don't express. SDK declaration: // Mermaid agent SDK available as the global `mermaid`. All calls are // synchronous and pure. Compose multi-step edits in one execute() call. // Code Mode is synchronous: async/await, Promise jobs, and dynamic import are not supported. type Result<T, E> = { ok: true; value: T } | { ok: false; error: E } type CheckMermaidSpec = string[] | { include?: string[]; expected?: string[]; required?: string[]; require?: string[] exclude?: string[]; absent?: string[]; forbidden?: string[]; forbid?: string[]; unexpected?: string[] exact?: boolean } interface CheckMermaidResult { ok: boolean; missing: string[]; unexpected: string[]; facts: string[] } type MermaidConfigScalar = string | number | boolean | null type MermaidConfigValue = MermaidConfigScalar | MermaidConfigValue[] | { [key: string]: MermaidConfigValue | undefined } type MermaidRuntimeConfig = { [key: string]: MermaidConfigValue | undefined theme?: string fontFamily?: string themeVariables?: { [key: string]: MermaidConfigValue | undefined; fontFamily?: string } timeline?: { [key: string]: MermaidConfigValue | undefined; disableMulticolor?: boolean; sectionFills?: string[]; sectionColours?: string[] } xyChart?: { [key: string]: MermaidConfigValue | undefined } gantt?: { [key: string]: MermaidConfigValue | undefined; displayMode?: string } useMaxWidth?: boolean useWidth?: number themeCSS?: string } type DiagramKind = 'flowchart' | 'state' | 'sequence' | 'class' | 'er' | 'timeline' | 'journey' | 'xychart' | 'architecture' | 'pie' | 'quadrant' | 'gantt' interface ValidDiagram { readonly kind: DiagramKind readonly meta: { frontmatter?: Record<string, unknown> initDirectives: { raw: string; parsed: Record<string, unknown> }[] comments: { text: string; line: number }[] accessibility: { title?: string; descr?: string } } readonly body: | { kind: 'flowchart'; graph: FlowchartGraph } | StateBody | SequenceBody | TimelineBody | ClassBody | ErBody | JourneyBody | ArchitectureBody | XyChartBody | PieBody | QuadrantBody | GanttBody | { kind: 'opaque'; family: DiagramKind; source: string } readonly canonicalSource: string // normalized renderer input; opaque fidelity uses body.source } type FlowchartValidDiagram = ValidDiagram & { body: { kind: 'flowchart'; graph: FlowchartGraph } } type StateValidDiagram = ValidDiagram & { body: StateBody } type SequenceValidDiagram = ValidDiagram & { body: SequenceBody } type TimelineValidDiagram = ValidDiagram & { body: TimelineBody } type ClassValidDiagram = ValidDiagram & { body: ClassBody } type ErValidDiagram = ValidDiagram & { body: ErBody } type JourneyValidDiagram = ValidDiagram & { body: JourneyBody } type ArchitectureValidDiagram = ValidDiagram & { body: ArchitectureBody } type XyChartValidDiagram = ValidDiagram & { body: XyChartBody } type PieValidDiagram = ValidDiagram & { body: PieBody } type QuadrantValidDiagram = ValidDiagram & { body: QuadrantBody } type GanttValidDiagram = ValidDiagram & { body: GanttBody } interface FlowchartGraph { direction: 'TD' | 'TB' | 'LR' | 'BT' | 'RL' nodes: Map<string, { id: string; label: string; shape: string }> edges: { source: string; target: string; label?: string; style: string hasArrowStart?: boolean; hasArrowEnd?: boolean; startMarker?: st

Parameters2

code	string	required	JavaScript to execute; mermaid.* SDK is global.
timeoutMs	number	optional	Optional CPU-time budget (default 5000ms, max 30000ms).

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "JavaScript to execute; mermaid.* SDK is global."
    },
    "timeoutMs": {
      "type": "number",
      "description": "Optional CPU-time budget (default 5000ms, max 30000ms)."
    }
  },
  "required": [
    "code"
  ]
}

render_svg

Render a Mermaid source string to themeable SVG. Returns { ok, svg }. Layout is deterministic: identical input produces identical geometry.

Parameters6

source	string	required	Mermaid source.
theme	string	optional	Named theme (one of: paper, dusk, zinc-light, zinc-dark, tokyo-night, tokyo-night-storm, tokyo-night-light, catppuccin-mocha, catppuccin-latte, nord, nord-light, dracula, github-light, github-dark, solarized-light, solarized-dark, one-dark, salmon, salmon-dark, tufte, tufte-dark).
bg	string	optional	Background CSS color (overrides theme).
fg	string	optional	Foreground CSS color (overrides theme).
style	any	optional	Style: a name (hand-drawn, excalidraw, pen-and-ink, freehand, watercolor, blueprint, tufte, accessible-high-contrast, patent-drawing, status-dashboard, ops-schematic, chalkboard, risograph, architectural-plan, publication-figure, or any theme name), an inline style record, or an array stack merged left → right. A colors-only style is a theme.
seed	number	optional	Re-rolls ink wobble of styled looks; never moves layout.

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Mermaid source."
    },
    "theme": {
      "type": "string",
      "description": "Named theme (one of: paper, dusk, zinc-light, zinc-dark, tokyo-night, tokyo-night-storm, tokyo-night-light, catppuccin-mocha, catppuccin-latte, nord, nord-light, dracula, github-light, github-dark, solarized-light, solarized-dark, one-dark, salmon, salmon-dark, tufte, tufte-dark)."
    },
    "bg": {
      "type": "string",
      "description": "Background CSS color (overrides theme)."
    },
    "fg": {
      "type": "string",
      "description": "Foreground CSS color (overrides theme)."
    },
    "style": {
      "description": "Style: a name (hand-drawn, excalidraw, pen-and-ink, freehand, watercolor, blueprint, tufte, accessible-high-contrast, patent-drawing, status-dashboard, ops-schematic, chalkboard, risograph, architectural-plan, publication-figure, or any theme name), an inline style record, or an array stack merged left → right. A colors-only style is a theme."
    },
    "seed": {
      "type": "number",
      "description": "Re-rolls ink wobble of styled looks; never moves layout."
    }
  },
  "required": [
    "source"
  ]
}

render_ascii

Render a Mermaid source string to text. Returns { ok, text }. useAscii true → plain ASCII (+,-,|); false/absent → Unicode box drawing (┌,─,│).

Parameters2

source	string	required	Mermaid source.
useAscii	boolean	optional	true = ASCII characters, false = Unicode (default).

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Mermaid source."
    },
    "useAscii": {
      "type": "boolean",
      "description": "true = ASCII characters, false = Unicode (default)."
    }
  },
  "required": [
    "source"
  ]
}

render_png

Rasterize a Mermaid source string to PNG. Returns { ok, png_base64 }. Hosted rendering uses resvg-wasm with bundled fonts; bytes may differ from the local napi renderer, so hosted PNG is a convenience surface, not part of the byte-determinism contract. For file/URL artifacts use the local stdio server.

Parameters5

source	string	required	Mermaid source.
scale	number	optional	Output scale multiplier (default 2 — retina; clamped to 0.1–8).
background	string	optional	CSS color string (default 'white').
style	any	optional	Style name \| record \| stack (same as render_svg). Hosted rasterization bundles the built-in style faces; custom unbundled fonts fall back to DejaVu.
seed	number	optional	Ink seed for styled looks.

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Mermaid source."
    },
    "scale": {
      "type": "number",
      "description": "Output scale multiplier (default 2 — retina; clamped to 0.1–8)."
    },
    "background": {
      "type": "string",
      "description": "CSS color string (default 'white')."
    },
    "style": {
      "description": "Style name | record | stack (same as render_svg). Hosted rasterization bundles the built-in style faces; custom unbundled fonts fall back to DejaVu."
    },
    "seed": {
      "type": "number",
      "description": "Ink seed for styled looks."
    }
  },
  "required": [
    "source"
  ]
}

verify

Parse and verify a Mermaid diagram without rendering it. Returns { ok, family, summary, warnings, layout: { bounds, nodes, edges } } for valid diagrams and { ok: false, errors } for parse failures. `family` is the detected diagram family and `summary` a one-line description — check them: ok:true only means the diagram is structurally valid, not that it is the kind you intended. Warnings use the layout-rubric codes.

Parameters1

source

string

required

Mermaid source.

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Mermaid source."
    }
  },
  "required": [
    "source"
  ]
}

describe

Describe a Mermaid diagram. format=text returns { ok, text } with one or two summary sentences; format=json returns { ok, tree } with the AX tree; format=facts returns { ok, facts } with deterministic semantic fact lines for machine checking (for example edge A -> B : label, member Duck +quack()).

Parameters2

source	string	required	Mermaid source.
format	string	optional	text (default), json AX tree, or facts semantic read-back.

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Mermaid source."
    },
    "format": {
      "type": "string",
      "enum": [
        "text",
        "json",
        "facts"
      ],
      "description": "text (default), json AX tree, or facts semantic read-back."
    }
  },
  "required": [
    "source"
  ]
}

mutate

Apply a list of structured edit ops to an existing Mermaid `source` and return the edited diagram. This is the declarative counterpart to `execute`: plain JSON in, plain JSON out, no sandbox. Prefer it for straightforward edits; reserve `execute` for logic the ops don't express. Returns { ok, family, source, verify:{ ok, warnings } } on success, or { ok:false, family, opIndex, error } — where `error` names the offending field and lists the valid ones — when an op is malformed or cannot apply. Ops apply in order and are all-or-nothing: the first failing op stops the batch (its position is `opIndex`) and the input is left untouched. Each op is { "kind": <op>, …fields }. Op kinds by family: flowchart: add_node(id, label, shape?, parent?), remove_node(id), rename_node(from, to), set_label(target, label), add_edge(from, to, label?, style?), remove_edge(id) state: add_state(id, label?, parent?), remove_state(id), rename_state(from, to), set_state_label(id, label), add_transition(from, to, label?, parent?), remove_transition(index?, from?, to?, parent?), set_transition_label(index?, from?, to?, label, parent?), make_composite(id, members, label?) sequence: add_participant(id, label?, participantKind?), remove_participant(id), add_message(from, to, text, style?), remove_message(index), set_message_text(index, text) timeline: set_title(title), add_section(label), remove_section(index), set_section_label(index, label), add_period(sectionIndex, label, events?), remove_period(sectionIndex, periodIndex), set_period_label(sectionIndex, periodIndex, label), add_event(sectionIndex, periodIndex, text), remove_event(sectionIndex, periodIndex, eventIndex), set_event_text(sectionIndex, periodIndex, eventIndex, text) class: set_title(title), add_class(id, label?, members?), remove_class(id), rename_class(from, to), add_member(class, text), remove_member(class, index), add_relation(from, to, relKind, label?), remove_relation(index), add_note(text, for?), remove_note(index) er: add_entity(id, attributes?), remove_entity(id), rename_entity(from, to), add_attribute(entity, text), remove_attribute(entity, index), add_relation(from, to, leftCard, rightCard, dashed?, label?), remove_relation(index) journey: set_title(title), add_section(label), remove_section(index), set_section_label(index, label), add_task(sectionIndex, text, score, actors?), remove_task(sectionIndex, taskIndex), set_task_text(sectionIndex, taskIndex, text), set_task_score(sectionIndex, taskIndex, score), set_task_actors(sectionIndex, taskIndex, actors), rename_actor(from, to) architecture: add_service(id, label?, icon?, group?), remove_service(id), rename_service(from, to), set_service_label(id, label), set_service_icon(id, icon), move_service(id, group), add_group(id, label?, icon?, parent?), remove_group(id), add_edge(from, to, fromSide, toSide, label?, hasArrowStart?, hasArrowEnd?), remove_edge(index?, id?) xychart: set_title(title), set_x_axis(axis), set_y_axis(axis), add_series(kind2, name?, values), remove_series(index), set_series_values(index, values), set_series_name(index, name), reorder_series(from, to) pie: set_title(title), set_show_data(showData), add_slice(label, value), remove_slice(label), rename_slice(from, to), set_slice_value(label, value), reorder_slice(from, to) quadrant: set_title(title), set_axis_labels(axis, near, far?), set_quadrant_label(quadrant, label), add_point(label, x, y), remove_point(label), move_point(label, x, y), rename_point(from, to) gantt: set_title(title), add_section(label), rename_section(index, label), remove_section(index), add_task(sectionIndex, label, taskId?, tags?, start?, end), remove_task(sectionIndex, taskIndex), rename_task(sectionIndex, taskIndex, label), set_task_status(sectionIndex, taskIndex, status), set_task_dates(sectionIndex, taskIndex, start?, end?)

Parameters2

source	string	required	Mermaid source to edit.
ops	array	required	Ordered list of edit ops; each is { kind, ...fields }.

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Mermaid source to edit."
    },
    "ops": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Ordered list of edit ops; each is { kind, ...fields }."
    }
  },
  "required": [
    "source",
    "ops"
  ]
}

build

Author a new Mermaid diagram from blank by folding a list of structured ops over an empty diagram of `family`. The declarative counterpart to hand-writing source. Returns the same envelope as `mutate`: { ok, family, source, verify } or { ok:false, family, opIndex, error }. Op kinds by family: flowchart: add_node(id, label, shape?, parent?), remove_node(id), rename_node(from, to), set_label(target, label), add_edge(from, to, label?, style?), remove_edge(id) state: add_state(id, label?, parent?), remove_state(id), rename_state(from, to), set_state_label(id, label), add_transition(from, to, label?, parent?), remove_transition(index?, from?, to?, parent?), set_transition_label(index?, from?, to?, label, parent?), make_composite(id, members, label?) sequence: add_participant(id, label?, participantKind?), remove_participant(id), add_message(from, to, text, style?), remove_message(index), set_message_text(index, text) timeline: set_title(title), add_section(label), remove_section(index), set_section_label(index, label), add_period(sectionIndex, label, events?), remove_period(sectionIndex, periodIndex), set_period_label(sectionIndex, periodIndex, label), add_event(sectionIndex, periodIndex, text), remove_event(sectionIndex, periodIndex, eventIndex), set_event_text(sectionIndex, periodIndex, eventIndex, text) class: set_title(title), add_class(id, label?, members?), remove_class(id), rename_class(from, to), add_member(class, text), remove_member(class, index), add_relation(from, to, relKind, label?), remove_relation(index), add_note(text, for?), remove_note(index) er: add_entity(id, attributes?), remove_entity(id), rename_entity(from, to), add_attribute(entity, text), remove_attribute(entity, index), add_relation(from, to, leftCard, rightCard, dashed?, label?), remove_relation(index) journey: set_title(title), add_section(label), remove_section(index), set_section_label(index, label), add_task(sectionIndex, text, score, actors?), remove_task(sectionIndex, taskIndex), set_task_text(sectionIndex, taskIndex, text), set_task_score(sectionIndex, taskIndex, score), set_task_actors(sectionIndex, taskIndex, actors), rename_actor(from, to) architecture: add_service(id, label?, icon?, group?), remove_service(id), rename_service(from, to), set_service_label(id, label), set_service_icon(id, icon), move_service(id, group), add_group(id, label?, icon?, parent?), remove_group(id), add_edge(from, to, fromSide, toSide, label?, hasArrowStart?, hasArrowEnd?), remove_edge(index?, id?) xychart: set_title(title), set_x_axis(axis), set_y_axis(axis), add_series(kind2, name?, values), remove_series(index), set_series_values(index, values), set_series_name(index, name), reorder_series(from, to) pie: set_title(title), set_show_data(showData), add_slice(label, value), remove_slice(label), rename_slice(from, to), set_slice_value(label, value), reorder_slice(from, to) quadrant: set_title(title), set_axis_labels(axis, near, far?), set_quadrant_label(quadrant, label), add_point(label, x, y), remove_point(label), move_point(label, x, y), rename_point(from, to) gantt: set_title(title), add_section(label), rename_section(index, label), remove_section(index), add_task(sectionIndex, label, taskId?, tags?, start?, end), remove_task(sectionIndex, taskIndex), rename_task(sectionIndex, taskIndex, label), set_task_status(sectionIndex, taskIndex, status), set_task_dates(sectionIndex, taskIndex, start?, end?)

Parameters2

family	string	required	Diagram family to author (one of: flowchart, state, sequence, timeline, class, er, journey, architecture, xychart, pie, quadrant, gantt).
ops	array	required	Ordered list of ops; each is { kind, ...fields }.

Raw schema

{
  "type": "object",
  "properties": {
    "family": {
      "type": "string",
      "description": "Diagram family to author (one of: flowchart, state, sequence, timeline, class, er, journey, architecture, xychart, pie, quadrant, gantt)."
    },
    "ops": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Ordered list of ops; each is { kind, ...fields }."
    }
  },
  "required": [
    "family",
    "ops"
  ]
}

README.md11 KBView on GitHub

Agentic Mermaid

Beautiful diagrams, made with your agent.

Agentic Mermaid is an open-source Mermaid toolkit for people who want AI agents to create diagrams that look finished: SVG and PNG renders, ASCII and Unicode for review, deterministic layout, and Style + Palette controls for brand colors, typography, strokes, fills, and backdrops.

It is forked from lukilabs/beautiful-mermaid. Published on npm as agentic-mermaid; the GitHub repository is adewale/agentic-mermaid; the canonical live site is agentic-mermaid.dev, a Cloudflare Workers deployment.

Agentic Mermaid: Mermaid source plus typed edit ops on the left, the verified SVG render in the middle, and the same diagram as ASCII on the right

Live Demo & Samples · Live Editor

Docs: docs index · getting started · agent guide · agent API cookbook · design system · skills · fork differences · vs Mermaid & Beautiful Mermaid · changelog

Why Agentic Mermaid

Use it when you want to describe a diagram in plain language and get back something you can publish without a design cleanup pass.

You want	Agentic Mermaid gives you
An agent to draft the diagram	Mermaid source plus a verified render path
Beautiful defaults	Built-in looks such as `watercolor`, `blueprint`, `hand-drawn`, and `publication-figure`
Brand fit	Style + Palette stacks and custom JSON palettes you can keep in your repo
Safe edits later	`parseMermaid` → family narrower → `mutate` → `verifyMermaid` → `serializeMermaid`
Reviewable artifacts	SVG, PNG, ASCII, Unicode, and JSON layout from the same source

The agent workflow is the guardrail behind the polish: agents should not guess from pixels, concatenate strings, or regenerate whole diagrams when a structured edit is available.

Highlights

12 diagram families — flowchart, state, architecture, sequence, class, ER, timeline, journey, XY chart, pie, quadrant, and Gantt.
SVG, PNG, ASCII, Unicode, JSON — one deterministic layout foundation for docs, decks, terminals, and agent workflows.
Synchronous, zero-DOM SVG renderer — no Puppeteer, no browser flash.
Composable styles — { style: ['hand-drawn', 'dracula'] } stacks a look over a palette; 15 full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (docs/style-authoring.md). seed re-rolls the ink, never the layout.
21 built-in themes + Shiki compatibility — a theme is a palette-only style: theme from two colors or a VS Code theme.
Agent-native editing — typed mutation for all twelve renderable families (flowchart/state, sequence, timeline, class, ER, journey, architecture, XY chart, pie, quadrant, Gantt); source-level round-trip only for opaque fallbacks (unmodeled syntax).
CLI + MCP + library — am, agentic-mermaid-mcp, agentic-mermaid, and agentic-mermaid/agent.

Installation

bash

npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaid
am --help
agentic-mermaid-mcp

For repository development, install from source and run the Bun entrypoints:

bash

git clone https://github.com/adewale/agentic-mermaid
cd agentic-mermaid
bun install
bun run build
bun run bin/am.ts --help
bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server

ESM-only. agentic-mermaid ships ES modules (there is no CommonJS build); require() consumers should use dynamic import() instead. Requires Node ≥ 18.

The am … commands shown below assume the published bin. From a source checkout, run them as bun run bin/am.ts … instead.

Output quick starts

Use agentic-mermaid/agent when you want one import path for styled renders, output formats, and the structured edit API.

SVG

import { renderMermaidSVG } from 'agentic-mermaid/agent'

const svg = renderMermaidSVG(`flowchart TD
  Start --> Done`, { security: 'strict' })

PNG

import { writeFileSync } from 'node:fs'
import { renderMermaidPNG } from 'agentic-mermaid/agent'

const png = renderMermaidPNG(`flowchart TD
  Start --> Done`, {
  fitTo: { width: 1200 },
  background: '#fff',
})

writeFileSync('diagram.png', png)

CLI equivalent:

bash

am render diagram.mmd --format png --output diagram.png

ASCII / Unicode

import { renderMermaidASCII } from 'agentic-mermaid/agent'

const unicode = renderMermaidASCII(`flowchart LR
  A --> B`)
const ascii = renderMermaidASCII(`flowchart LR
  A --> B`, { useAscii: true })

Agent quick start

If your coding agent can read repo files, point it at:

skills/agentic-mermaid-diagram-workflow/SKILL.md for diagram authoring/editing.
skills/agentic-mermaid-live-editor/SKILL.md for editor changes.

If it only has shell access:

bash

am --agent-instructions
am capabilities --json
am preview diagram.mmd --security strict --open
am mutate diagram.mmd --op '{"kind":"add_node","id":"Cache","label":"Cache"}' --json

Zero-install prompt for a coding agent: read https://agentic-mermaid.dev/llms.txt and follow the parse → narrow → mutate → verify → serialize workflow. To wire Agentic Mermaid into another repo, run npx agentic-mermaid init-agent (or bun run bin/am.ts init-agent from a source checkout); it writes a non-clobbering AGENTS.md section, root skills/ bundle, and .mcp.json sample.

Use strict preview for human inspection and mutate --op/--ops for verified one-shot or batched edits.

For multi-step MCP edits, connect agentic-mermaid-mcp and use Code Mode execute(code) with the same mermaid.* SDK names. Stdio is the default transport; agentic-mermaid-mcp --transport http starts HTTP/SSE and managed PNG file/URL artifacts. See the agent API cookbook for copy-pasteable library, CLI, and MCP recipes.

MCP server

Agentic Mermaid ships a Model Context Protocol server so MCP-capable agents can render and safely edit diagrams without shelling out.

Self-hosted (default). agentic-mermaid-mcp runs a stdio server exposing execute (Code Mode sandbox), render_png, and describe. Package runners can use npx -y agentic-mermaid mcp; the mcp argument routes the package-name binary to the same stdio server. Add --transport http for HTTP/SSE with managed PNG file/URL artifacts. See docs/mcp-http-transport.md and docs/mcp-code-mode-rationale.md.
Hosted. A stateless Streamable HTTP endpoint is available at https://agentic-mermaid.dev/mcp (tools: execute, render_svg, render_ascii, render_png, verify, describe, mutate, build; 64 KB input caps). It is MCP JSON-RPC only, not a REST render API. Hosted execute runs the same mermaid.* facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.

Local-first is the default posture: prefer the library, CLI, or a self-hosted MCP for anything sensitive, offline, larger than the hosted caps, or needing local PNG file/URL artifacts. The hosted endpoint is a public, unauthenticated convenience for zero-install render/verify/describe and bounded structured edits.

Structured edit example

import { parseMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'

const parsed = parseMermaid('flowchart TD\n  API --> DB')
if (!parsed.ok) throw new Error('parse failed')

const flow = asFlowchart(parsed.value)
if (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)

const next = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })
if (!next.ok) throw new Error(next.error.message)

const verify = verifyMermaid(next.value)
if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))

const source = serializeMermaid(next.value)

Rules:

Use asFlowchart / asState / asSequence / asTimeline / asClass / asEr / asJourney / asArchitecture / asXyChart / asPie / asQuadrant / asGantt before mutating existing diagrams.
Mutation ops use kind, not type.
Run verifyMermaid before every commit point.
Do not call mutate on opaque fallback bodies; the narrower returns null for unmodeled syntax.

Supported diagram families

Family	Parse	Verify	Render	Structured mutate
Flowchart / state	✓	✓	SVG/PNG/ASCII	✓
Sequence	✓	✓	SVG/PNG/ASCII	simple messages/participants
Timeline	✓	✓	SVG/PNG/ASCII	✓
Class	✓	✓	SVG/PNG/ASCII	✓
ER	✓	✓	SVG/PNG/ASCII	✓
Journey	✓	✓	SVG/PNG/ASCII	modeled subset (BUILD-15)
XY chart	✓	✓	SVG/PNG/ASCII	modeled subset (BUILD-16)
Pie	✓	✓	SVG/PNG/ASCII	✓
Quadrant	✓	✓	SVG/PNG/ASCII	✓
Architecture	✓	✓	SVG/PNG/ASCII	modeled subset (BUILD-17)
Gantt	✓	✓	SVG/PNG/ASCII	sections/tasks; calendar directives ride along verbatim

See diagram families for examples and compatibility notes.

Live editor and examples

Examples — supported families, Style + Palette combinations, and the rich shared examples corpus.
Live editor — SVG/PNG exports and URL sharing.
examples/agent-loop.ts
examples/mcp-vs-cli-complex-diagrams.ts
examples/agent-improve-auth-flow.ts

Attribution

Agentic Mermaid is a fork of Beautiful Mermaid by Luki Labs. The ASCII rendering engine is based on mermaid-ascii by Alexander Grooff and extended for Agentic Mermaid.

License

MIT

Install

Tools (8)

executerender_svgrender_asciirender_pngverifydescribemutatebuild

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "agentic-mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "agentic-mermaid@0.1.1",
        "mcp"
      ]
    }
  }
}

Topics

execute

render_svg

render_ascii

render_png

verify

describe

mutate

build

Agentic Mermaid

Why Agentic Mermaid

Highlights

Installation

Output quick starts

SVG

PNG

ASCII / Unicode

Agent quick start

MCP server

Structured edit example

Supported diagram families

More documentation

Live editor and examples

Attribution

License

Install