mcp-mermaidjs-to-image (v0.1.0)

A high-performance Model Context Protocol (MCP) server that converts Mermaid.js diagram syntax into crisp, high-resolution PNG images.

Powered by the official Mermaid.js v12.3.0 engine, providing native support for 37+ diagram types (including native UML Use-Case, Swimlanes, Cloud Architecture, Network Packets, Kanban, and more).

Compatible with Antigravity, Cline, Codex, Claude Code, Cursor, and Claude Desktop.

Key Features

• Latest Mermaid.js Engine (v12.3.0): Complete native support for all 37+ diagram types—UML Use-Case (usecase-beta), Swimlanes (swimlane-beta), Flowcharts, Sequence Diagrams, Class Diagrams, Cloud Architecture, Network Packets, Kanban, GitGraphs, Mindmaps, and more.

• 3-Step AI Workflow: Implements a progressive disclosure architecture:

  1. get_supported_diagrams: Discover available keywords, aliases, and categories.

  2. get_diagram_syntax_guide: Retrieve precise grammar rules, connectors, and verified examples on demand.

  3. render_mermaid_to_png: Render crisp PNGs with mandatory keyword validation.

• Mandatory Keyword Validation: Rejects requests missing or having invalid diagram_type, returning a categorized list of available keywords to eliminate guesswork and syntax hallucinations.

• Smart Alias Normalization: Transparently maps aliases (usecase / use-case → usecase-beta, swimlane / swimlanes → swimlane-beta) across arguments and syntax headers.

• Multimodal AI Ready: Returns the rendered diagram directly as an MCP image/png block so multimodal AI assistants can visually inspect and verify their diagrams in real time.

• AI-Optimized Verbose Diagnostics: If syntax fails, returns actionable diagnostics with line numbers, code frames (> Line N | ... ^), and diagram-specific remediation hints with isError: true so the AI can self-correct immediately.

• Sub-100ms Rendering: Uses a persistent headless browser singleton with lazy initialization and an automatic 5-minute idle shutdown.

• High-DPI Retina Output: Renders at 2x scale by default (configurable up to 3x or 4x).

• Flexible Themes & Backgrounds: Supports default, neutral, dark, forest, and base themes, plus solid or transparent backgrounds.

• Zero Cloud Dependencies: Runs 100% locally with automatic fallback to system Microsoft Edge or Google Chrome if needed.

Related MCP server: Mermaid MCP Server

The 3-Step AI Agent Workflow

To avoid flooding the AI's context window while guaranteeing 100% syntax compliance, the server separates discovery, syntax knowledge, and image rasterization into three focused tools:

flowchart TD
    AI["🤖 Calling AI Agent"]

    subgraph MCP ["📦 mcp-mermaidjs-to-image"]
        T1["🛠️ 1. get_supported_diagrams\n(Mermaid v12.3.0 Catalog)"]
        T2["🛠️ 2. get_diagram_syntax_guide\n(Exact grammar, connectors, pitfalls & examples)"]
        T3["🛠️ 3. render_mermaid_to_png\n(Mandatory diagram_type + high-DPI rasterization)"]
    end

    AI -->|"1. Discover available types"| T1
    T1 -.->|"Returns keywords & points to guide"| AI
    AI -->|"2. Query syntax for specific type (e.g. usecase-beta)"| T2
    T2 -.->|"Returns precise syntax & verified examples"| AI
    AI -->|"3. Render diagram (diagram_type + syntax)"| T3
    T3 -->|"Returns high-resolution PNG image"| AI

MCP Tools Reference

Tool 1: get_supported_diagrams

Returns the Mermaid.js engine version (v12.3.0) and the complete catalog of all 37+ supported diagram types, keywords, aliases, and categories.

Parameters:

Output:

• Formatted markdown table of supported diagram types with accepted aliases and a guide prompt to query get_diagram_syntax_guide.

Tool 2: get_diagram_syntax_guide

Returns authoritative syntax rules, keyword requirements, relationship connectors, common pitfalls, and verified working examples for a specific diagram type.

Parameters:

Output:

• Exact header declaration requirements (e.g. usecase-beta\ndirection LR).

• Core syntax elements and item declarations.

• Connector operators (e.g. -->, ..> :include, ..> :extend, --|>).

• Common pitfalls to avoid (e.g. "Do NOT write system { }, use systemBoundary ... end").

• Minimal and complete verified working examples.

Tool 3: render_mermaid_to_png

Converts Mermaid diagram syntax directly into a high-resolution PNG image.

Parameters:

Output:

• image: Base64-encoded image/png buffer for inline AI inspection.

• text: Execution summary with dimensions, scale factor, and saved path.

Tool 4: render_mermaid_file

Reads a local .mmd or .mermaid file and renders it directly to a PNG file on disk.

Parameters:

Mandatory Keyword Validation & Rejection Protocol

To prevent syntax confusion and incorrect diagram type selection, render_mermaid_to_png and render_mermaid_file strictly require the diagram_type parameter.

If an AI passes an invalid or missing diagram_type, the tool immediately responds with isError: true and an informative rejection message:

❌ **Diagram Render Rejected: Mandatory Diagram Type Missing or Invalid**

Unrecognized diagram type: "invalid_type".

Mermaid.js engine v12.3.0 requires an explicit `diagram_type` parameter to ensure accurate rendering and prevent syntax mismatch.

### Available Keywords by Category:
- **UML & Process**: `usecase-beta`, `swimlane-beta`, `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `agentflow-beta`
- **Architecture & Systems**: `architecture`, `C4Context`, `C4Container`, `C4Component`, `packet-beta`, `block-beta`, `flowchart-elk`, `eventmodeling`, `wardley-beta`
- **Project Planning**: `gantt`, `timeline`, `kanban`, `gitGraph`, `journey`
- **Charts & Visual Analytics**: `pie`, `quadrantChart`, `xychart-beta`, `sankey-beta`, `mindmap`, `radar-beta`, `venn-beta`, `treemap`, `ishikawa-beta`, `cynefin-beta`
- **Grammar & Specs**: `railroad-beta`, `railroad-ebnf-beta`, `railroad-abnf-beta`, `railroad-peg-beta`, `requirementDiagram`, `treeView-beta`

💡 **How to proceed**:
1. Call `get_supported_diagrams` to browse all diagram options and accepted aliases.
2. Call `get_diagram_syntax_guide({ diagram_type: "<keyword>" })` to retrieve exact syntax rules and verified examples.
3. Provide the valid `diagram_type` alongside your `mermaid_syntax` to render your diagram.

Supported Diagram Types (Mermaid v12.3.0)

Quick Setup & Client Configurations

1. Build & Link Locally

git clone <repo-url> mcp-mermaidjs-to-image
cd mcp-mermaidjs-to-image
npm install
npm run build
npm link

Compiled entry point: c:\Users\Public\Downloads\projects\mcp-mermaidjs-to-image\dist\index.js

2. Client Configurations

Antigravity

Add to your Antigravity MCP configuration (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "mermaid-to-image": {
      "command": "node",
      "args": ["c:/Users/Public/Downloads/projects/mcp-mermaidjs-to-image/dist/index.js"],
      "disabled": false
    }
  }
}

Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "mermaid-to-image": {
      "command": "node",
      "args": ["c:/Users/Public/Downloads/projects/mcp-mermaidjs-to-image/dist/index.js"]
    }
  }
}

Claude Code (CLI)

claude mcp add mermaid-to-image -- node c:/Users/Public/Downloads/projects/mcp-mermaidjs-to-image/dist/index.js

Codex / Cursor (mcp.json)

{
  "mcpServers": {
    "mermaid-to-image": {
      "command": "node",
      "args": ["c:/Users/Public/Downloads/projects/mcp-mermaidjs-to-image/dist/index.js"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mermaid-to-image": {
      "command": "node",
      "args": ["c:/Users/Public/Downloads/projects/mcp-mermaidjs-to-image/dist/index.js"]
    }
  }
}

Verbose Error Diagnostics Example

When an AI provides broken syntax (e.g. B -- invalid syntax -- C), the tool sets isError: true and responds with detailed markdown:

❌ **Mermaid Render Failed: Syntax Error**

- **Diagram Type**: `graph`
- **Location**: Line 3

**Code Context**:

1 | graph TD
2 |     A[Start] --> B(Valid Step)

3 | B -- invalid syntax -- C | ^ 4 | C --> D[End]

**Error Details**:
Lexical error on line 3. Unrecognized text.
...nvalid syntax -- C    C --> D[End
-----------------------^

💡 **Remediation Hint**:
Check connector arrows (e.g. `-->`, `---`, `-.->`, `==>`). If you have labels on links, wrap them in pipes: `A -->|label| B` or use `A -- label --> B`. Ensure node labels containing special characters (brackets, parens, quotes) are enclosed in double quotes, e.g. `id["Node (Label)"]`.

Testing

Run the automated test suites:

# 1. Renderer unit tests
npm test

# 2. Full MCP Tools protocol & validation test suite
node --import tsx test/mcp-tools-suite.test.ts

Output:

🧪 Starting MCP Tools Test Suite...
✅ Connected to MCP Server via Stdio Transport.

--- Test 1: List Tools ---
Available tools: [
  'get_supported_diagrams',
  'get_diagram_syntax_guide',
  'render_mermaid_to_png',
  'render_mermaid_file'
]
✅ Test 1 Passed: All 4 tools registered.

--- Test 2: get_supported_diagrams ---
✅ Test 2 Passed: get_supported_diagrams returned engine version & catalog.

--- Test 3: get_diagram_syntax_guide (usecase-beta) ---
✅ Test 3 Passed: get_diagram_syntax_guide returned detailed grammar rules and examples.

--- Test 4: Rejection on Invalid diagram_type ---
✅ Test 4 Passed: Properly rejected invalid diagram_type and returned keyword feedback.

--- Test 5: Render Use-Case Diagram with Alias Normalization ---
✅ Test 5 Passed: Successfully normalized alias and rendered native UML Use-Case diagram to PNG.

--- Test 6: Render Swimlane Diagram ---
✅ Test 6 Passed: Successfully rendered native Swimlanes diagram to PNG.

🎉 ALL 6 TESTS PASSED SUCCESSFULLY!

License

MIT