Mermaid MCP App

A streamable MCP App server that renders interactive Mermaid diagrams with live preview, theme switching, and fullscreen editing.

Demo

Interactive diagram editing with live preview, pan/zoom controls, and fullscreen mode

Features

- Complete Rendering - Waits for full diagram generation before displaying (no partial/streaming output)
- SVGO Optimization - Automatic SVG optimization reduces file size by ~85%
- Dark Mode - Auto-detects system theme with neutral gray palette
- Interactive Pan/Zoom - Navigate large diagrams with wheel zoom and drag controls
- Fullscreen Editor - Edit Mermaid syntax with live preview, zoom controls (+/−/1:1)
- Theme Switching - Light, Dark, or Custom (agent-provided) themes
- All Diagram Types - Flowcharts, sequence, class, state, ER, gantt, pie, git graphs, and more
- Export with Spinner - Copy SVGO-optimized SVG to clipboard (spinner indicates progress)
- Client-side Rendering - No server dependencies, runs entirely in the browser

Quick Start

Remote (Vercel)

Use the hosted endpoint: https://mermaid-mcp-app.vercel.app/mcp

Add as a remote MCP server in your client. For example, in claude.ai: Settings → Connectors → Add custom connector → paste the URL above.

Installation

npm install

Development

Start the development server with hot-reload:

npm run dev

The server will start at http://localhost:3001/mcp

Build

Build for production:

npm run build

This creates:
- dist/mcp-app.html - Single-file bundled UI
- dist/server.js - MCP server
- dist/index.js - CLI entry point

Usage

Local (HTTP)

npm run serve
or
node dist/index.js

Local (stdio)

node dist/index.js --stdio

Vercel Deployment

Deploy to Vercel for remote access:

npx vercel

The MCP endpoint will be available at https://mermaid-mcp-app.vercel.app/mcp

MCP Tools

read_me

Returns comprehensive Mermaid syntax reference with examples for all diagram types.

Usage: Call this before create_view to learn Mermaid syntax.

create_view

Renders a Mermaid diagram. The diagram is fully rendered before being displayed (no progressive/streaming rendering).

Parameters:
- mermaid (string, required) - Mermaid diagram syntax
- theme (string, optional) - One of: default (auto-detect), forest, dark, neutral, base
- title (string, optional) - Title to display above the diagram

Notes:
- Default theme auto-detects system dark mode and applies neutral gray palette
- Agent can specify built-in Mermaid themes (forest, dark, neutral, base) which appear as "Custom" in UI
- Fullscreen mode includes zoom controls (+, −, 1:1, wheel zoom) and pan/drag

Example:

{

  "mermaid": "flowchart TD\n  A[Start] --> B[End]",

  "theme": "forest",

  "title": "Simple Flow"

}

export_svg (app-only)

Export the rendered diagram as optimized SVG using SVGO. Called by the UI export button (spinner icon during processing).

Optimization:
- SVGO reduces SVG size by ~85% (e.g., 334KB → 51KB)
- Rounds coordinates to 2 decimal places
- Preserves viewBox and mermaid IDs for proper rendering

Architecture

- Server: Node.js with Express + MCP SDK
- Supports both Streamable HTTP and stdio transports
- Stateless per-request design (no sessions)
- UI: React 19 with Mermaid.js
- Loaded from CDN (jsdelivr for Mermaid, esm.sh for React) via importmap
- Client-side rendering for zero server dependencies
- Single-file HTML bundle (~402KB) via Vite + vite-plugin-singlefile
- SVGO server-side optimization for exports
- Build: TypeScript + Vite + Bun
- Type-safe server and client code
- Optimized production bundles

File Structure

mermaid-mcp-app/
├── src/
│   ├── server.ts          # MCP server with tool registration + SVGO
│   ├── main.ts            # Transport layer (HTTP + stdio)
│   ├── mcp-app.html       # HTML shell with importmap
│   ├── mcp-app.tsx        # React UI component
│   ├── theme-vars.ts      # Mermaid theme color palettes
│   └── global.css         # Styles (dark mode, animations)
├── api/
│   └── mcp.ts            # Vercel serverless handler
├── dist/                  # Build output
├── scripts/
│   └── setup-bun.mjs     # Auto-install bun
├── package.json
├── tsconfig.json          # Client TS config
├── tsconfig.server.json   # Server TS config
├── vite.config.ts         # Vite bundler config
├── vercel.json           # Vercel deployment config
└── manifest.json         # MCP app manifest

Technologies

- MCP SDK - Model Context Protocol
- ext-apps - MCP Apps extension
- Mermaid.js - Diagram generation
- SVGO - SVG optimization (server-side)
- React 19 - UI framework
- Vite - Build tool
- TypeScript - Type safety
- Bun - Build bundler

License

MIT