ai-diagrams-mcp

An MCP (Model Context Protocol) server that renders Mermaid diagrams to an interactive HTML viewer with zoom/pan capabilities. Zero configuration required.

Features

• Interactive Viewer - Pan and zoom diagrams with pinch gestures or buttons
• Multiple Diagrams - Render multiple diagrams in a single view
• Mermaid Themes - Support for default, dark, forest, and neutral themes
• Light/Dark Mode - Automatic system preference detection with manual toggle
• Shareable Links - Upload diagrams and get public HTTPS links (no account required)
• Cross-Platform - Works on macOS, Linux, and Windows

Quick Start

npx -y ai-diagrams-mcp@latest

Or install globally:

npm install -g ai-diagrams-mcp

Configuration by AI Tool

~/.claude.json or project .mcp.json

{
  "mcpServers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

Or via CLI: claude mcp add ai-diagrams -- npx -y ai-diagrams-mcp@latest

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

~/.cursor/mcp.json or Settings → Features → MCP

{
  "mcpServers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

.vscode/mcp.json in workspace or via Command Palette: MCP: Add Server

{
  "servers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

Click MCP Servers icon → Configure → Edit MCP Settings

{
  "mcpServers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

Settings → Open Settings (JSON)

{
  "context_servers": {
    "ai-diagrams": {
      "command": {
        "path": "npx",
        "args": ["-y", "ai-diagrams-mcp@latest"]
      }
    }
  }
}

~/.codex/config.toml

[mcp_servers.ai-diagrams]
command = "npx"
args = ["-y", "ai-diagrams-mcp@latest"]

Or via CLI: codex mcp add ai-diagrams -- npx -y ai-diagrams-mcp@latest

Settings → Tools → MCP Server

{
  "mcpServers": {
    "ai-diagrams": {
      "command": "npx",
      "args": ["-y", "ai-diagrams-mcp@latest"]
    }
  }
}

Usage

Once configured, ask your AI assistant to render diagrams:

"Create a flowchart showing the user authentication process"

"Draw a sequence diagram for the API request flow"

"Generate an ER diagram for a blog database"

The render_diagram tool accepts:

• diagrams - Array of { title?: string, code: string } objects
• theme - Optional: 'default' | 'dark' | 'forest' | 'neutral'
• share - Optional: true to upload and get a public shareable link
• shareExpiry - Optional: '1h' | '12h' | '24h' | '72h' (default: '1h')

Example

// Tool call - local only
{
  "diagrams": [
    {
      "title": "Authentication Flow",
      "code": "graph TD\n  A[User] -->|Login| B[Auth Server]\n  B -->|Token| A"
    }
  ],
  "theme": "dark"
}

// Tool call - with shareable link
{
  "diagrams": [
    {
      "title": "Authentication Flow",
      "code": "graph TD\n  A[User] -->|Login| B[Auth Server]\n  B -->|Token| A"
    }
  ],
  "share": true
}

Supported Diagram Types

Mermaid supports many diagram types including:

• Flowcharts
• Sequence Diagrams
• Class Diagrams
• State Diagrams
• Entity Relationship Diagrams
• Gantt Charts
• Pie Charts
• Mind Maps
• Timeline
• Git Graphs
• Quadrant Charts

See Mermaid documentation for full syntax reference.

Viewer Features

• Zoom Controls - Use +/- buttons or pinch gesture on trackpad
• Pan - Click and drag to move around
• Reset - Return to original view
• Theme Toggle - Switch between light, dark, and system modes

Sharing

Generate temporary public links to share diagrams with colleagues:

{
  "diagrams": [...],
  "share": true,
  "shareExpiry": "24h"  // Options: 1h, 12h, 24h, 72h
}

• No account required
• Full interactive viewer with zoom/pan
• Links expire automatically (default: 1h)

Output Files

Each render creates two files in the temp directory:

• mermaid-viewer-{uuid}.html - Interactive viewer (opened in browser)
• mermaid-source-{uuid}.json - Diagram source for reference/iteration

The source file makes it easy to adjust and re-render diagrams.

Development

# Install dependencies
npm install
cd viewer && npm install && cd ..

# Build everything
npm run build

# Run tests
npm test

# Start the server
npm start

Tech Stack

• Runtime: Node.js 22+
• Frontend: Vue 3 + Tailwind CSS 4 + Vite
• Diagrams: Mermaid.js v11 (via CDN)
• Zoom/Pan: @panzoom/panzoom
• MCP SDK: @modelcontextprotocol/sdk

Resources

• Model Context Protocol - MCP specification
• Mermaid.js - Diagram syntax documentation
• MCP Servers Directory - Community MCP servers

License

MIT

Made by LaserFocused OÜ