Skip to content
Back to search

mermaid-mcp-server

A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/peng-shawn--mermaid-mcp-server/badge.svg)](/listings/peng-shawn--mermaid-mcp-server)

HTML

<a href="/listings/peng-shawn--mermaid-mcp-server"><img src="/api/listings/peng-shawn--mermaid-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

To install Mermaid Diagram Generator for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server):

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 238 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Mermaid MCP Server
  2. A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images or SVG files. This server allows AI assistants and other applications to generate visual diagrams from textual descriptions using the Mermaid markdown syntax.
  3. ## Features
  4. - Converts Mermaid diagram code to PNG images or SVG files
  5. - Supports multiple diagram themes (default, forest, dark, neutral)
  6. - Customizable background colors
  7. - Uses Puppeteer for high-quality headless browser rendering
  8. - Implements the MCP protocol for seamless integration with AI assistants
  9. - Flexible output options: return images/SVG directly or save to disk
  10. - Error handling with detailed error messages
  11. ## How It Works
  12. The server uses Puppeteer to launch a headless browser, render the Mermaid diagram to SVG, and optionally capture a screenshot of the rendered diagram. The process involves:
  13. 1. Launching a headless browser instance
  14. 2. Creating an HTML template with the Mermaid code
  15. 3. Loading the Mermaid.js library
  16. 4. Rendering the diagram to SVG
  17. 5. Either saving the SVG directly or taking a screenshot as PNG
  18. 6. Either returning the image/SVG directly or saving it to disk
  19. ## Requirements
  20. - Node.js 22.12.0 or later
  21. > **Security notice:** versions before 0.3.0 depend on Puppeteer and Mermaid releases with known vulnerabilities. Please upgrade to 0.3.0 or later. The configurations below use `@latest` so `npx` picks up new releases.
  22. ## Build
  23. ```bash
  24. npx tsc
  25. ```
  26. ## Usage
  27. ### Use with Claude desktop
  28. ```json
  29. {
  30. "mcpServers": {
  31. "mermaid": {
  32. "command": "npx",
  33. "args": ["-y", "@peng-shawn/mermaid-mcp-server@latest"]
  34. }
  35. }
  36. }
  37. ```
  38. ### Use with Cursor and Cline
  39. ```bash
  40. env CONTENT_IMAGE_SUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server@latest
  41. ```
  42. You can find a list of mermaid diagrams under `./diagrams`, they are created using Cursor agent with prompt: "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work"
  43. ### Run with inspector
  44. Run the server with inspector for testing and debugging:
  45. ```bash
  46. npx @modelcontextprotocol/inspector node dist/index.js
  47. ```
  48. The server will start and listen on stdio for MCP protocol messages.
  49. Learn more about inspector [here](https://modelcontextprotocol.io/docs/tools/inspector).
  50. ### Installing via Smithery
  51. To install Mermaid Diagram Generator for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server):
  52. ```bash
  53. npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude
  54. ```
  55. ### Docker and Smithery Environments
  56. When running in Docker containers (including via Smithery), you may need to handle Chrome dependencies:
  57. 1. The server now attempts to use Puppeteer's bundled browser by default
  58. 2. If you encounter browser-related errors, you have two options:
  59. **Option 1: During Docker image build:**
  60. - Set `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true` when installing Puppeteer
  61. - Install Chrome/Chromium in your Docker container
  62. - Set `PUPPETEER_EXECUTABLE_PATH` at runtime to point to the Chrome installation
  63. **Option 2: Use Puppeteer's bundled Chrome:**
  64. - Ensure your Docker container has the necessary dependencies for Chrome
  65. - No need to set `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD`
  66. - The code will use the bundled browser automatically
  67. For Smithery users, the latest version should work without additional configuration.
  68. ## API
  69. The server exposes a single tool:
  70. - `generate`: Converts Mermaid diagram code to a PNG image or SVG file
  71. - Parameters:
  72. - `code`: The Mermaid diagram code to render
  73. - `theme`: (optional) Theme for the diagram. Options: "default", "forest", "dark", "neutral"
  74. - `backgroundColor`: (optional) Background color for the diagram, e.g. 'white', 'transparent', '#F0F0F0'
  75. - `outputFormat`: (optional) Output format for the diagram. Options: "png", "svg" (defaults to "png")
  76. - `name`: Name for the generated file (required when CONTENT_IMAGE_SUPPORTED=false)
  77. - `folder`: Absolute path to save the image/SVG to (required when CONTENT_IMAGE_SUPPORTED=false)
  78. The behavior of the `generate` tool depends on the `CONTENT_IMAGE_SUPPORTED` environment variable:
  79. - When `CONTENT_IMAGE_SUPPORTED=true` (default): The tool returns the image/SVG directly in the response
  80. - When `CONTENT_IMAGE_SUPPORTED=false`: The tool saves the image/SVG to the specified folder and returns the file path
  81. ## Environment Variables
  82. - `CONTENT_IMAGE_SUPPORTED`: Controls whether images are returned directly in the response or saved to disk
  83. - `true` (default): Images are returned directly in the response
  84. - `false`: Images are saved to disk, requiring `name` and `folder` parameters
  85. ## Examples
  86. ### Basic Usage
  87. ```javascript
  88. // Generate a flowchart with default settings
  89. {
  90. "code": "flowchart TD\n A[Start] --> B{Is it?}\n B -->|Yes| C[OK]\n B -->|No| D[End]"
  91. }
  92. ```
  93. ### With Theme and Background Color
  94. ```javascript
  95. // Generate a sequence diagram with forest theme and light gray background
  96. {
  97. "code": "sequenceDiagram\n Alice->>John: Hello John, how are you?\n John-->>Alice: Great!",
  98. "theme": "forest",
  99. "backgroundColor": "#F0F0F0"
  100. }
  101. ```
  102. ### Saving to Disk (when CONTENT_IMAGE_SUPPORTED=false)
  103. ```javascript
  104. // Generate a class diagram and save it to disk as PNG
  105. {
  106. "code": "classDiagram\n Class01 <|-- AveryLongClass\n Class03 *-- Class04\n Class05 o-- Class06",
  107. "theme": "dark",
  108. "name": "class_diagram",
  109. "folder": "/path/to/diagrams"
  110. }
  111. ```
  112. ### Generating SVG Output
  113. ```javascript
  114. // Generate a state diagram as SVG
  115. {
  116. "code": "stateDiagram-v2\n [*] --> Still\n Still --> [*]\n Still --> Moving\n Moving --> Still\n Moving --> Crash\n Crash --> [*]",
  117. "outputFormat": "svg",
  118. "name": "state_diagram",
  119. "folder": "/path/to/diagrams"
  120. }
  121. ```
  122. ## FAQ
  123. ### Doesn't Claude desktop already support mermaid via canvas?
  124. Yes, but it doesn't support the `theme` and `backgroundColor` options. Plus, having a dedicated server makes it easier to create mermaid diagrams with different MCP clients.
  125. ### Why do I need to specify CONTENT_IMAGE_SUPPORTED=false when using with Cursor?
  126. Cursor doesn't support inline images in responses yet.
  127. ## Publishing
  128. This project uses GitHub Actions to automate the publishing process to npm.
  129. ### Method 1: Using the Release Script (Recommended)
  130. 1. Make sure all your changes are committed and pushed
  131. 2. Run the release script with either a specific version number or a semantic version increment:
  132. ```bash
  133. # Using a specific version number
  134. npm run release 0.1.4
  135. # Using semantic version increments
  136. npm run release patch # Increments the patch version (e.g., 0.1.3 → 0.1.4)
  137. npm run release minor # Increments the minor version (e.g., 0.1.3 → 0.2.0)
  138. npm run release major # Increments the major version (e.g., 0.1.3 → 1.0.0)
  139. ```
  140. 3. The script will:
  141. - Validate the version format or semantic increment
  142. - Check if you're on the main branch
  143. - Detect and warn about version mismatches between files
  144. - Update all version references consistently (package.json, package-lock.json, and index.ts)
  145. - Create a single commit with all version changes
  146. - Create and push a git tag
  147. - The GitHub workflow will then automatically build and publish to npm
  148. ### Method 2: Manual Process
  149. 1. Update your code and commit the changes
  150. 2. Create and push a new tag with the version number:
  151. ```bash
  152. git tag v0.1.4 # Use the appropriate version number
  153. git push origin v0.1.4
  154. ```
  155. 3. The GitHub workflow will automatically:
  156. - Build the project
  157. - Publish to npm with the version from the tag
  158. Note: You need to set up the `NPM_TOKEN` secret in your GitHub repository settings. To do this:
  159. 1. Generate an npm access token with publish permissions
  160. 2. Go to your GitHub repository → Settings → Secrets and variables → Actions
  161. 3. Create a new repository secret named `NPM_TOKEN` with your npm token as the value
  162. ## Badges
  163. [![smithery badge](https://smithery.ai/badge/@peng-shawn/mermaid-mcp-server)](https://smithery.ai/server/@peng-shawn/mermaid-mcp-server)
  164. <a href="https://glama.ai/mcp/servers/lzjlbitkzr">
  165. <img width="380" height="200" src="https://glama.ai/mcp/servers/lzjlbitkzr/badge" alt="mermaid-mcp-server MCP server" />
  166. </a>
  167. ## License
  168. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.