mermaid_preview
Render Mermaid diagrams with live browser preview, auto-refresh on updates, and customizable themes, dimensions, and formats.
Instructions
Render a Mermaid diagram and open it in browser with live reload. Takes Mermaid diagram code as input and generates a live preview. Supports themes (default, forest, dark, neutral), custom backgrounds, dimensions, and quality scaling. The diagram will auto-refresh when updated. Use mermaid_save to save to disk. IMPORTANT: Automatically use this tool whenever you create a Mermaid diagram for the user. NOTE: Sequence diagrams do not support style directives - avoid using 'style' statements in sequenceDiagram.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diagram | Yes | The Mermaid diagram code to render | |
| preview_id | Yes | ID for this preview session. Use different IDs for multiple diagrams (e.g., 'architecture', 'flow', 'sequence'). | |
| format | No | Output format (default: svg) | svg |
| theme | No | Theme of the chart (default: default) | default |
| background | No | Background color for pngs/svgs. Example: transparent, red, '#F0F0F0' (default: white) | white |
| width | No | Diagram width in pixels (default: 800) | |
| height | No | Diagram height in pixels (default: 600) | |
| scale | No | Scale factor for higher quality output (default: 2) |
Implementation Reference
- src/handlers.ts:147-192 (handler)Core handler function that validates inputs, renders the Mermaid diagram using mermaid-cli, sets up live preview for SVG format, and returns success or error response.
export async function handleMermaidPreview(args: any) { const diagram = args.diagram as string; const previewId = args.preview_id as string; const format = (args.format as string) || "svg"; const theme = (args.theme as string) || "default"; const background = (args.background as string) || "white"; const width = (args.width as number) || 800; const height = (args.height as number) || 600; const scale = (args.scale as number) || 2; if (!diagram) { throw new Error("diagram parameter is required"); } if (!previewId) { throw new Error("preview_id parameter is required"); } const previewDir = getPreviewDir(previewId); await mkdir(previewDir, { recursive: true }); const liveFilePath = getDiagramFilePath(previewId, format); try { await saveDiagramSource(previewId, diagram, { theme, background, width, height, scale }); await renderDiagram( { diagram, previewId, format, theme, background, width, height, scale }, liveFilePath ); if (format === "svg") { const { serverUrl, hasConnections } = await setupLivePreview(previewId, liveFilePath); return createLivePreviewResponse(liveFilePath, format, serverUrl, hasConnections); } else { return createStaticRenderResponse(liveFilePath, format); } } catch (error) { return { content: [ { type: "text", text: `Error rendering Mermaid diagram: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } } - src/index.ts:37-84 (schema)Input schema defining the parameters for the mermaid_preview tool, including required fields and defaults.
inputSchema: { type: "object", properties: { diagram: { type: "string", description: "The Mermaid diagram code to render", }, preview_id: { type: "string", description: "ID for this preview session. Use different IDs for multiple diagrams (e.g., 'architecture', 'flow', 'sequence').", }, format: { type: "string", enum: ["png", "svg", "pdf"], description: "Output format (default: svg)", default: "svg", }, theme: { type: "string", enum: ["default", "forest", "dark", "neutral"], description: "Theme of the chart (default: default)", default: "default", }, background: { type: "string", description: "Background color for pngs/svgs. Example: transparent, red, '#F0F0F0' (default: white)", default: "white", }, width: { type: "number", description: "Diagram width in pixels (default: 800)", default: 800, }, height: { type: "number", description: "Diagram height in pixels (default: 600)", default: 600, }, scale: { type: "number", description: "Scale factor for higher quality output (default: 2)", default: 2, }, }, required: ["diagram", "preview_id"], }, - src/index.ts:28-85 (registration)Registration of the 'mermaid_preview' tool in the TOOL_DEFINITIONS array, including name, description, and reference to inputSchema.
{ name: "mermaid_preview", description: "Render a Mermaid diagram and open it in browser with live reload. " + "Takes Mermaid diagram code as input and generates a live preview. " + "Supports themes (default, forest, dark, neutral), custom backgrounds, dimensions, and quality scaling. " + "The diagram will auto-refresh when updated. Use mermaid_save to save to disk. " + "IMPORTANT: Automatically use this tool whenever you create a Mermaid diagram for the user. " + "NOTE: Sequence diagrams do not support style directives - avoid using 'style' statements in sequenceDiagram.", inputSchema: { type: "object", properties: { diagram: { type: "string", description: "The Mermaid diagram code to render", }, preview_id: { type: "string", description: "ID for this preview session. Use different IDs for multiple diagrams (e.g., 'architecture', 'flow', 'sequence').", }, format: { type: "string", enum: ["png", "svg", "pdf"], description: "Output format (default: svg)", default: "svg", }, theme: { type: "string", enum: ["default", "forest", "dark", "neutral"], description: "Theme of the chart (default: default)", default: "default", }, background: { type: "string", description: "Background color for pngs/svgs. Example: transparent, red, '#F0F0F0' (default: white)", default: "white", }, width: { type: "number", description: "Diagram width in pixels (default: 800)", default: 800, }, height: { type: "number", description: "Diagram height in pixels (default: 600)", default: 600, }, scale: { type: "number", description: "Scale factor for higher quality output (default: 2)", default: 2, }, }, required: ["diagram", "preview_id"], }, }, - src/index.ts:143-146 (registration)Dispatch logic in the CallToolRequest handler that routes 'mermaid_preview' calls to the handleMermaidPreview function.
case "mermaid_preview": result = await handleMermaidPreview(args); mcpLogger.info(`CallTool completed: ${toolName}`); return result; - src/handlers.ts:38-89 (helper)Key helper function that executes the mermaid-cli to render the diagram to the specified format and copies to live file path.
async function renderDiagram(options: RenderOptions, liveFilePath: string): Promise<void> { const { diagram, previewId, format, theme, background, width, height, scale } = options; mcpLogger.info(`Rendering diagram: ${previewId}`, { format, theme, width, height }); const tempDir = join(tmpdir(), "claude-mermaid"); await mkdir(tempDir, { recursive: true }); const inputFile = join(tempDir, `diagram-${previewId}.mmd`); const outputFile = join(tempDir, `diagram-${previewId}.${format}`); await writeFile(inputFile, diagram, "utf-8"); const args = [ "-y", "@mermaid-js/mermaid-cli", "-i", inputFile, "-o", outputFile, "-t", theme, "-b", background, "-w", width.toString(), "-H", height.toString(), "-s", scale.toString(), ]; if (format === "pdf") { args.push("--pdfFit"); } mcpLogger.debug(`Executing mermaid-cli`, { args }); try { const { stdout, stderr } = await execFileAsync("npx", args); if (stderr) { mcpLogger.debug(`mermaid-cli stderr`, { stderr }); } await copyFile(outputFile, liveFilePath); mcpLogger.info(`Diagram rendered successfully: ${previewId}`); } catch (error) { mcpLogger.error(`Diagram rendering failed: ${previewId}`, { error: error instanceof Error ? error.message : String(error), }); throw error; } }