Diagram Converter MCP Server

An MCP (Model Context Protocol) server for rendering, validating, and exporting Mermaid diagrams. Features bidirectional editor sync — the only Mermaid MCP server with live UI integration.

Features

• 13 MCP tools — validate, render, diff, batch export, editor sync, and more
• 20 diagram types — flowchart, sequence, class, state, gantt, mindmap, ER, and more
• Multiple render/export paths — SVG text, PNG base64, and file export helpers
• Bidirectional editor sync — LLM reads/writes the browser editor in real-time
• Content-addressable LRU cache — 10-entry cache with per-entry TTL for fast re-renders
• Enhanced error messages — line/column locations, suggestions, and documentation links
• Built-in editor server — internal HTTP server for editor sync, no external process needed
• Safe port-collision fallback — only uses an external server when /api/mcp/health is compatible
• Path security hardening — traversal/null-byte/symlink escape protections for static serving and export paths

Quick Start

Prerequisites

• Node.js 20+ (20.19+ recommended)
• (Optional) The diagram-converter build output is only used for UI preview. Core MCP features work standalone.

Run

npx diagram-converter-mcp

MCP Client Configuration

Common format (only the config file location differs per client):

{
  "mcpServers": {
    "diagram-converter-mcp": {
      "command": "npx",
      "args": ["-y", "diagram-converter-mcp"]
    }
  }
}

Pinned vs Floating version

• Production/CI (recommended): [email protected] (pinned)
• Quick experiment: diagram-converter-mcp (latest)
• Add environment variables only as needed:
  • DIAGRAM_CONVERTER_MCP_AUTO_START=true
  • DIAGRAM_CONVERTER_MCP_ALLOW_REMOTE_UI=false
  • See the Environment Variables section below for details

Export Notes

• mermaid_validate is still the fastest syntax gate before rendering/export.
• From v0.2.11, the headless renderer prefers SVG text labels (htmlLabels: false, markdownAutoWrap: false) and normalizes SVG dimensions after render, which fixes the major flowchart regressions seen in earlier 0.2.x releases.
• Simple and mid-size flowcharts now produce practical SVG/PNG output again, including sane viewBox values and visible PNG text labels.
• Large or browser-dependent layouts can still diverge from Mermaid's in-browser output, so use a browser renderer when you need pixel-level parity.
• For documentation workflows, both generated image assets and Markdown mermaid code blocks are valid. Choose images when you want checked-in artifacts, and code blocks when you want GitLab/GitHub to render live.

Local source (development only)

{
  "mcpServers": {
    "diagram-converter-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE_PATH_TO/diagram-converter-mcp/dist/index.js"]
    }
  }
}

Keep the mcpServers block identical across clients — only the config file path differs.

Tools

| Tool | Description | |------|-------------| | mermaid_validate | Validate Mermaid syntax without rendering (fast, cheap) | | mermaid_render | Render diagram to SVG (text) or PNG (base64 image) | | mermaid_detect_type | Detect diagram type from source code | | mermaid_diff | Compare two Mermaid sources and return structured line-level changes | | mermaid_batch_render | Render multiple diagrams in one call and save to files | | mermaid_export | Export last render to SVG or PNG file | | mermaid_export_both | Re-render and export both SVG + PNG files | | mermaid_get_current | Read current state of the UI editor | | mermaid_update_editor | Push new code to the UI editor (real-time sync) | | mermaid_get_history | Retrieve history of MCP-initiated editor updates | | mermaid_open_preview | Open the diagram-converter UI in a browser | | mermaid_list_templates | List all available diagram templates with code | | mermaid_list_types | List supported diagram types with documentation URLs |

Usage Examples

Validate before rendering:

"Validate this Mermaid syntax first, then decide whether to export or keep it as a markdown mermaid block"

Render and export:

"Render this sequence diagram as PNG and save it to ./docs/"

Editor sync:

"Read the current diagram from the editor, improve it, and push it back"

Explore templates:

"Show me the available diagram templates"

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | DIAGRAM_CONVERTER_MCP_UI_PORT | 4269 | UI server port | | DIAGRAM_CONVERTER_MCP_UI_HOST | 127.0.0.1 | UI server host | | DIAGRAM_CONVERTER_MCP_UI_BASE_URL | http://127.0.0.1:4269 | Full UI server origin only (no path/query/hash; overrides host/port) | | DIAGRAM_CONVERTER_MCP_ALLOW_REMOTE_UI | false | Allow non-loopback UI_BASE_URL (disabled by default for safety) | | DIAGRAM_CONVERTER_EXPORT_DIR | process.cwd() | Default export directory | | DIAGRAM_CONVERTER_MCP_CACHE_MAX_BYTES | 20971520 | Approximate in-memory render cache cap in bytes | | DIAGRAM_CONVERTER_MCP_RENDER_QUEUE_MAX | 32 | Max queued+running render jobs before fast-fail | | DIAGRAM_CONVERTER_MCP_RENDER_TIMEOUT | 120000 | Per-render timeout in ms (increase for slow CI environments) | | DIAGRAM_CONVERTER_MCP_AUTO_START | true | Auto-start internal editor server on first editor sync call |

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | macOS (Intel / Apple Silicon) | Supported | | | Linux (x64, ARM64) | Supported | glibc and musl (Alpine) | | Windows (x64) | Supported | Via npm/npx | | WSL | Supported | Browser opens via Windows host | | Docker / CI | Supported | Headless — no browser UI needed |

Documentation

• Architecture
• AI Engine Architecture
• CI/CD
• Configuration
• Operations
• Tools Reference
• Troubleshooting

These docs are included in the npm package under docs/.

Contact & Support

Distributed via npm. Source available on GitLab. For bug reports, feedback, or inquiries, please contact: [email protected]

License

MIT