Mermaid MCP Architecture

Mermaid MCP is a Model Context Protocol server that provides programmatic Mermaid diagram generation to LLM agents. It wraps the mcp-mermaid npm package (v0.4.1) in a Docker container with headless Chromium, enabling AI agents to convert Mermaid syntax into PNG images (base64), raw SVG markup, saved PNG files, or public mermaid.ink URLs on demand.

The server exposes a single MCP tool (generate_mermaid_diagram) over SSE transport on port 3033, routed through Traefik at mermaid-mcp.home. It is part of the MCP Tools Stack alongside Grafana MCP, Hugging Face MCP, and PubMed MCP.

Key value: Allows any MCP-compatible agent (Claude Code, Gemini CLI, n8n) to generate diagrams without requiring a browser or local Mermaid installation.

MCP Tools

Transport

SSE

Port

3033

Base Image

Node 20

Output Formats

Package

mcp-mermaid 0.4.1

2. Runtime Architecture

Diagram A -- Runtime Request Flow

Request Flow

An MCP client (Claude Code, Gemini CLI, n8n) sends a generate_mermaid_diagram tool call over SSE transport to mermaid-mcp.home.
Traefik terminates TLS and proxies the request to the mermaid-mcp container on port 3033.
The MCP server validates the input (Mermaid syntax, theme, background color, output type) using Zod schemas.
mermaid-isomorphic renders the Mermaid syntax into SVG using a cached renderer instance.
If a raster output is needed (base64 or file), Playwright drives headless Chromium to capture a PNG screenshot of the rendered SVG.
The result is returned to the client as base64 image data, raw SVG text, a saved file path, or a public mermaid.ink URL.

5. Public Interfaces

MCP Tools

The server exposes a single tool via the MCP protocol:

Tool	Description
`generate_mermaid_diagram`	Generate mermaid diagram and chart with mermaid syntax dynamically. Converts Mermaid text definitions into rendered diagrams.

Input Parameters

Parameter	Type	Required	Default	Description
`mermaid`	`string`	Yes	--	The Mermaid diagram syntax to render (e.g., `graph TD; A-->B;`)
`theme`	`enum`	No	`default`	Diagram theme: `default`, `base`, `forest`, `dark`, `neutral`
`backgroundColor`	`string`	No	`white`	Background color for the diagram (any CSS color value)
`outputType`	`enum`	No	`base64`	Output format: `base64` (PNG as base64), `svg` (raw SVG markup), `mermaid` (echo input), `file` (save PNG to disk), `svg_url` (mermaid.ink SVG link), `png_url` (mermaid.ink PNG link)

Output Types

Output Type	Return Format	Use Case
`base64`	MCP image content (PNG, base64-encoded)	Inline display in MCP clients
`svg`	Raw SVG markup as text	Embedding in HTML documents
`mermaid`	Echo of input Mermaid syntax	Validation / pass-through
`file`	File path to saved PNG on disk	Persistent file output
`svg_url`	Public mermaid.ink SVG URL	Remote sharing without local render
`png_url`	Public mermaid.ink PNG URL	Remote sharing without local render

Transport Endpoints

Transport	Endpoint	Port	Status
SSE (Server-Sent Events)	`/sse`	3033	Active
Streamable HTTP	`/mcp`	3033	Available (not deployed)
stdio	--	--	Available (local use)

Health Check

curl -s http://mermaid-mcp.home/sse

6. Repository Structure

Local Source (Custom Dockerfile Only)

_mcp-tools/
  mermaid-mcp/
    Dockerfile              # Custom image: node:20-bookworm-slim + mcp-mermaid + Chromium
  docker-compose.yml        # Stack-level compose (all 4 MCP servers)
  .env                      # Credentials (Grafana, HF, NCBI tokens)
  README.md                 # Stack documentation

Installed Package (Inside Container)

/usr/local/lib/node_modules/mcp-mermaid/
  build/
    index.js                # CLI entrypoint (transport selection)
    server.js               # MCP server creation + tool handler registration
    tools/
      index.js              # Tool schema (Zod) + tool metadata definition
    services/
      index.js              # Transport exports
      sse.js                # SSE transport (Express-based)
      stdio.js              # stdio transport
      streamable.js         # Streamable HTTP transport
    utils/
      index.js              # Utility exports
      render.js             # Mermaid rendering via mermaid-isomorphic + Playwright
      mermaidUrl.js          # mermaid.ink URL generation
      logger.js             # Logging utility
      schema.js             # Zod-to-JSON-schema converter
  package.json              # Dependencies and scripts

Component Classification

Component	Classification	Role
`Dockerfile`	Primary	Container image definition -- the only custom code in this repo
`server.js`	Primary	MCP server core -- tool registration, request dispatch, error handling
`tools/index.js`	Primary	Tool definition with Zod schema validation
`utils/render.js`	Primary	Rendering pipeline -- mermaid-isomorphic + Playwright screenshot
`services/sse.js`	Secondary	SSE transport layer (deployed configuration)
`utils/mermaidUrl.js`	Auxiliary	Generates public mermaid.ink URLs for svg_url/png_url output types
`docker-compose.yml`	Secondary	Stack orchestration (shared with 3 other MCP servers)

7. Deployment & Operations

Container Specification

Property	Value
Container name	`mermaid-mcp`
Base image	`node:20-bookworm-slim`
Installed package	`[email protected]` (global npm install)
Browser	Chromium (installed via Playwright with system deps)
Exposed port	3033
CMD	`mcp-mermaid -t sse -p 3033 -H 0.0.0.0`
Restart policy	`unless-stopped`
Docker network	`hosting_web` (external)
Environment variables	None required
Traefik labels	`traefik.enable=false` (routed via file provider in dynamic.yml)
External hostname	`mermaid-mcp.home` (LAN only via Pi-hole DNS)

Build and Deploy

# Build the image
cd /home/rod/_rod/_mcp-tools
docker compose build --no-cache mermaid-mcp

# Deploy
docker compose up -d mermaid-mcp

# View logs
docker logs -f mermaid-mcp

# Health check
curl -s http://mermaid-mcp.home/sse

Dockerfile Walkthrough

FROM node:20-bookworm-slim
WORKDIR /app

# Skip Playwright's browser download during npm install,
# then install separately with system dependencies
ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
RUN npm install -g mcp-mermaid

# Playwright installs Chromium + required Debian system libs
RUN npx playwright install --with-deps chromium

EXPOSE 3033
CMD ["mcp-mermaid", "-t", "sse", "-p", "3033", "-H", "0.0.0.0"]

Why two-step Playwright install? Setting PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 during npm install prevents downloading browsers redundantly. The explicit npx playwright install --with-deps chromium then installs only Chromium along with the correct system dependencies (libatk, libcups, libnss3, etc.) for the Debian Bookworm base.

8. Dependencies

Runtime Dependencies

Package	Version	Role
`@modelcontextprotocol/sdk`	^1.11.4	MCP protocol implementation (Server, transport, schemas)
`mermaid-isomorphic`	^3.0.4	Server-side Mermaid rendering (SVG output)
`playwright`	^1.52.0	Headless Chromium automation for PNG screenshot capture
`express`	^5.1.0	HTTP server for SSE and Streamable HTTP transports
`cors`	^2.8.5	Cross-origin request support for HTTP transports
`zod`	^3.25.16	Schema validation for tool input parameters
`zod-to-json-schema`	^3.24.5	Converts Zod schemas to JSON Schema for MCP tool definitions

System Dependencies (Inside Container)

Dependency	Source	Purpose
Node.js 20 LTS	Base image (`node:20-bookworm-slim`)	JavaScript runtime
Chromium	Playwright (`npx playwright install --with-deps chromium`)	Headless browser for PNG rendering
Debian Bookworm system libs	Playwright `--with-deps`	libatk, libnss3, libcups, libxss, libgbm, etc. required by Chromium

Infrastructure Dependencies

Service	Required	Role
Docker + Docker Compose	Yes	Container runtime and orchestration
`hosting_web` network	Yes	Shared Docker network for Traefik connectivity
Traefik	Yes	Reverse proxy, TLS termination, routing via `dynamic.yml`
Pi-hole DNS	Yes	Resolves `mermaid-mcp.home` to 10.0.1.6
mermaid.ink (external)	No	Only used for `svg_url` / `png_url` output types

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated -- regenerate after significant changes.