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 fromlukilabs/beautiful-mermaid. Published on npm asagentic-mermaid; the GitHub repository isadewale/agentic-mermaid; the canonical live site isagentic-mermaid.dev, a Cloudflare Workers deployment.

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

- Descriptor-registered diagram families— built-ins and namespaced extensions share one discovery and capability contract.
- SVG, PNG, ASCII, Unicode, JSON— one resolved request with explicit graphical, terminal, and positioned-layout projections.
- Synchronous, zero-DOM SVG renderer— no Puppeteer, no browser flash.
- Composable styles—{ style: ['hand-drawn', 'dracula'] }stacks a look over a palette; discoverable 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).seedre-rolls the ink, never the layout.
- Discoverable palettes + Shiki compatibility— a theme is a palette-only style: discover the canonical catalog at runtime, theme from two colors, or adapt a VS Code theme.
- Agent-native editing— typed mutation for every registered renderable family; source-level round-trip only for opaque fallbacks containing unmodeled syntax.
- CLI + MCP + library—am,agentic-mermaid-mcp,agentic-mermaid,agentic-mermaid/agent, and the browser/workerd-safeagentic-mermaid/agent/core. Audit reports and trusted host-resource helpers remain repository tooling instead of published runtime entry points.

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

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

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-mermaidships ES modules (there is no CommonJS build);require()consumers should use dynamicimport()instead. Requires Node ≥ 22.

Theam …examples below name the published bin. After a project-local npm install, invoke it from a shell asnpx --no-install agentic-mermaid …(or from an npm script asam …). From a source checkout, usebun run bin/am.ts …instead.

Useagentic-mermaid/agentwhen you want one import path for styled renders, output formats, and the structured edit API.

import { renderMermaidSVG } from 'agentic-mermaid/agent' const svg = renderMermaidSVG(flowchart TD Start --> Done, { security: 'strict' })

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)

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

import { renderMermaidASCII } from 'agentic-mermaid/agent' const unicode = renderMermaidASCII(flowchart LR A --> B) const ascii = renderMermaidASCII(flowchart LR A --> B, { useAscii: true })

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

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

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

For multi-step MCP edits, connectagentic-mermaid-mcpand use Code Modeexecute(code)with the samemermaid.SDK names. Stdio is the default transport;agentic-mermaid-mcp --transport httpstarts HTTP/SSE and managed PNG file/URL artifacts. See theagent API cookbookfor copy-pasteable library, CLI, and MCP recipes.

- Self-hosted (default).agentic-mermaid-mcpruns a stdio server exposingexecute(Code Mode sandbox),describe_sdk(one family's mutation schema on demand),render_png, anddescribe. Package runners can usenpx -y agentic-mermaid mcp; themcpargument routes the package-name binary to the same stdio server. Add--transport httpfor HTTP/SSE with managed PNG file/URL artifacts. Seedocs/mcp-http-transport.mdanddocs/mcp-code-mode-rationale.md.
- Hosted.A stateless Streamable HTTP endpoint is available athttps://agentic-mermaid.dev/mcp(tools:execute,describe_sdk,render_svg,render_ascii,render_png,verify,describe,mutate,build; 64 KB input caps). Calldescribe_sdkfor compact signatures or exact fields before authoring unfamiliar ops. It is MCP JSON-RPC only, not a REST render API. Hostedexecuteruns the samemermaid.facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.

Directory maintainers can use the canonicalMCP listing record. Hosted data handling is described in the[MCP privacy notice.

…