Mermaid & AntV Charts: Diagrams and Data Visualization

Two MCP servers handle the majority of our visualization needs: Mermaid MCP (port 3010) for diagrams and Chart MCP (port 3011) for data charts. This guide covers both tools with emphasis on theming and practical usage.

Mermaid MCP

Mermaid renders diagrams from a constrained text syntax via Playwright. LLMs generate valid Mermaid reliably because the syntax is well-represented in training data and heavily constrained.

Supported diagram types

• Flowcharts — process flows, decision trees
• Sequence diagrams — API interactions, message flows
• Class diagrams — object models
• State diagrams — state machines
• Entity-Relationship — database schemas
• Gantt charts — project timelines
• Architecture diagrams — system components
• Git graphs — branch visualization
• Pie charts — simple proportional data
• Mindmaps — hierarchical brainstorming

Theming with themeVariables

Full control over Mermaid’s appearance uses the base theme with themeVariables. Place this directive at the top of your Mermaid code:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

All confirmed working variables:

Variable	Controls
primaryColor	Main node background
primaryTextColor	Main node text
primaryBorderColor	Main node border
lineColor	Edge/arrow lines
secondaryColor	Secondary node background
tertiaryColor	Tertiary elements
fontFamily	Global font
fontSize	Global font size
background	Diagram background
mainBkg	Default node background
nodeBorder	Default node border
textColor	General text
labelTextColor	Edge labels
nodeTextColor	Node text
edgeLabelBackground	Edge label background

MCP parameters

• backgroundColor — set the overall image background color (works independently of themeVariables)

Quick theme presets

Dark mode:

Forest (green tones):

Neutral (grayscale):

Custom (full control):

Always use 'theme': 'base' when specifying custom themeVariables. Other themes override your customizations.

Best practices for AI generation

1. Keep diagrams focused — one concept per diagram, not everything at once
2. Use descriptive node IDs — auth[Authentication] not A[Authentication]
3. Limit nesting depth — 3-4 levels max for readability
4. Prefer flowchart TD (top-down) for processes, LR (left-right) for timelines
5. Use subgraphs to group related nodes

Chart MCP (AntV)

Chart MCP renders data charts using AntV’s charting library. Charts are rendered via CDN and returned as public URLs (not local files).

Supported chart types (27 total)

Basic: area, bar, column, line, pie, scatter

Statistical: boxplot, histogram, violin

Hierarchical: treemap, sankey, funnel, waterfall

Specialized: dual_axes, radar, venn, liquid, word_cloud

Diagrams (via chart engine): fishbone_diagram, flow_diagram, mind_map, network_graph, organization_chart

Note: The diagram types overlap with Mermaid and Infographic. Use Chart MCP for these when you need data-driven diagram generation; use Mermaid when you need precise control over diagram structure.

Theming

Theme presets:

{
  "theme": "dark"
}

Available themes: dark, default, academy

⚠️ Avoid academy theme — it overrides custom palettes. Stick to dark or default when using custom colors.

Custom palette:

{
  "theme": "dark",
  "style": {
    "palette": ["#d8e84e", "#4ecdc4", "#ff6b6b", "#45b7d1", "#96ceb4"],
    "backgroundColor": "#151719"
  }
}

Hand-drawn sketch style:

{
  "style": {
    "texture": "rough"
  }
}

The rough texture applies a hand-drawn sketch aesthetic to any chart type — combine with dark theme and custom palette for distinctive visuals.

Example: Branded dark bar chart

{
  "type": "bar",
  "theme": "dark",
  "style": {
    "palette": ["#d8e84e", "#4ecdc4", "#ff6b6b"],
    "backgroundColor": "#151719"
  },
  "data": [
    { "category": "Q1", "value": 120 },
    { "category": "Q2", "value": 180 },
    { "category": "Q3", "value": 150 },
    { "category": "Q4", "value": 210 }
  ],
  "xField": "category",
  "yField": "value"
}

Important notes

• Charts render to CDN URLs — the output is a public URL, not a local file
• 27 chart types cover most data visualization needs
• Palette + dark theme is the primary branding lever
• texture: 'rough' for sketch-style aesthetics

When to Use Which

Scenario	Tool	Why
Process flowchart	Mermaid	Best syntax, most reliable generation
API sequence diagram	Mermaid	Purpose-built for this
Database ER diagram	Mermaid	Native ER support
Bar/line/pie chart	Chart MCP	Data-driven, automatic axes/legends
Statistical distribution	Chart MCP	Boxplot, violin, histogram
Flow relationships	Chart MCP	Sankey, network graph
Project timeline	Mermaid	Gantt chart support
Word cloud	Chart MCP	Only option
Architecture overview	Mermaid	Architecture diagram type
Branded infographic layout	Infographic MCP	See AntV Infographic Guide
Cross-tool brand identity	Brand Theming for AI Agents	Unified palette + theme across all tools

Comparison with Previous Approaches

The original approach in our data visualization guide recommended Vega-Lite with VlConvert for chart generation. With Chart MCP now available:

• Vega-Lite remains a solid specification format but requires local tooling (VlConvert). Chart MCP handles rendering as a service.
• Chart MCP provides 27 chart types with theming, no local dependencies, CDN-delivered output.
• Mermaid MCP replaces the need for mmdc CLI — rendering is handled by the MCP server via Playwright.

The MCP architecture means agents don’t need to manage rendering toolchains. Specify what you want, get an image back.

---

Reference compiled 2026-02-19 for commune AI agent workflows.