Skip to content
Back to search

claude-mermaid

MarketplaceWorks with Claude CodeGitHub

MCP Server to previewing mermaid diagrams with live reload

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/veelenga/claude-mermaid with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/veelenga/claude-mermaid'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/veelenga--claude-mermaid/badge.svg)](/listings/veelenga--claude-mermaid)

HTML

<a href="/listings/veelenga--claude-mermaid"><img src="/api/listings/veelenga--claude-mermaid/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

1. Install

**Plugin Install (Recommended)**

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add veelenga/claude-mermaid
/plugin install claude-mermaid@claude-mermaid

Then restart Claude Code to activate the plugin.

**From npm:**

npm install -g claude-mermaid

**From source:**

git clone https://github.com/veelenga/claude-mermaid.git
cd claude-mermaid
npm install && npm run build && npm install -g .

2. Verify Installation

**Plugin install:** The MCP server is configured automatically. Just verify:

/mcp

You should see `mermaid` in the MCP server list.

**npm install:** Configure the MCP server manually:

claude mcp add --scope user mermaid claude-mermaid

Then verify:

claude mcp list

You should see `mermaid: claude-mermaid - ✓ Connected`

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.

.claude-plugin/marketplace.json · Manifest · 14 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. {
  2. "name": "claude-mermaid",
  3. "owner": {
  4. "name": "veelenga",
  5. "url": "https://github.com/veelenga"
  6. },
  7. "plugins": [
  8. {
  9. "name": "claude-mermaid",
  10. "source": "./",
  11. "description": "MCP server for previewing Mermaid diagrams in Claude Code"
  12. }
  13. ]
  14. }
README.md · README · 469 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. # Claude Mermaid MCP Server
  2. MCP server for rendering Mermaid diagrams in Claude Code with **live reload** functionality and a built-in skill for expert guidance.
  3. Automatically renders diagrams in your browser with real-time updates as you refine them. Perfect for iterative diagram development and documentation workflows.
  4. ![Demo](https://raw.githubusercontent.com/veelenga/claude-mermaid/main/assets/demo.gif)
  5. ## ✨ Features
  6. - 🔄 **Live Reload** - Diagrams auto-refresh in your browser as you edit
  7. - 🎨 **Multiple Save Formats** - Export to SVG, PNG, or PDF
  8. - 🌈 **Themes** - Choose from default, forest, dark, or neutral themes
  9. - 📐 **Customizable** - Control dimensions, scale, and background colors
  10. - 🪄 **Interactive Preview** - Pan diagrams by dragging, zoom with browser controls, reset position with one click
  11. - ⬇️ **Browser Export** - Download diagrams as SVG or PNG directly from the preview
  12. - 🗂️ **Multiple Previews** - Use `preview_id` to work on multiple diagrams simultaneously
  13. - 💾 **Persistent Working Files** - Live previews are stored under `~/.config/claude-mermaid/live`
  14. - 🤖 **Built-in Skill** - Includes a Claude skill with best practices and expert guidance for creating diagrams
  15. ## Architecture
  16. <details>
  17. <summary>Project Architecture Diagram</summary>
  18. ![Architecture Diagram](https://raw.githubusercontent.com/veelenga/claude-mermaid/main/assets/architecture.png)
  19. </details>
  20. <details>
  21. <summary>User Workflow Diagram</summary>
  22. ![User Workflow Diagram](https://raw.githubusercontent.com/veelenga/claude-mermaid/main/assets/workflow.png)
  23. </details>
  24. <details>
  25. <summary>Dependencies Diagram</summary>
  26. ![Dependencies Diagram](https://raw.githubusercontent.com/veelenga/claude-mermaid/main/assets/dependencies.png)
  27. </details>
  28. ## 🚀 Quick Start
  29. ### 1. Install
  30. **Plugin Install (Recommended)**
  31. In Claude Code, add the marketplace and install the plugin:
  32. ```bash
  33. /plugin marketplace add veelenga/claude-mermaid
  34. /plugin install claude-mermaid@claude-mermaid
  35. ```
  36. Then restart Claude Code to activate the plugin.
  37. **From npm:**
  38. ```bash
  39. npm install -g claude-mermaid
  40. ```
  41. **From source:**
  42. ```bash
  43. git clone https://github.com/veelenga/claude-mermaid.git
  44. cd claude-mermaid
  45. npm install && npm run build && npm install -g .
  46. ```
  47. ### 2. Verify Installation
  48. **Plugin install:** The MCP server is configured automatically. Just verify:
  49. ```bash
  50. /mcp
  51. ```
  52. You should see `mermaid` in the MCP server list.
  53. **npm install:** Configure the MCP server manually:
  54. ```bash
  55. claude mcp add --scope user mermaid claude-mermaid
  56. ```
  57. Then verify:
  58. ```bash
  59. claude mcp list
  60. ```
  61. You should see `mermaid: claude-mermaid - ✓ Connected`
  62. ## 🔌 Other MCP Client Configurations
  63. While this server is optimized for Claude Code, it can work with any MCP-compatible client. Here's how to configure it for other popular tools:
  64. <details>
  65. <summary><strong>Codex</strong></summary>
  66. Add to your Codex MCP settings file (`~/.codex/mcp_settings.json`):
  67. ```json
  68. {
  69. "mcpServers": {
  70. "mermaid": {
  71. "command": "claude-mermaid"
  72. }
  73. }
  74. }
  75. ```
  76. Or configure via Codex CLI:
  77. ```bash
  78. codex mcp add mermaid claude-mermaid
  79. ```
  80. </details>
  81. <details>
  82. <summary><strong>Cursor</strong></summary>
  83. Add to your Cursor MCP config file (`.cursor/mcp.json` or settings):
  84. ```json
  85. {
  86. "mcpServers": {
  87. "mermaid": {
  88. "command": "claude-mermaid"
  89. }
  90. }
  91. }
  92. ```
  93. Or use Cursor's settings UI:
  94. 1. Open Cursor Settings (Cmd/Ctrl + ,)
  95. 2. Navigate to MCP Servers
  96. 3. Add a new server with command: `claude-mermaid`
  97. </details>
  98. <details>
  99. <summary><strong>VSCode with Cline Extension</strong></summary>
  100. If using the [Cline extension](https://github.com/cline/cline) for VSCode:
  101. 1. Open VSCode settings (Cmd/Ctrl + ,)
  102. 2. Search for "Cline MCP"
  103. 3. Add to MCP Settings JSON:
  104. ```json
  105. {
  106. "mcpServers": {
  107. "mermaid": {
  108. "command": "claude-mermaid"
  109. }
  110. }
  111. }
  112. ```
  113. </details>
  114. <details>
  115. <summary><strong>Windsurf</strong></summary>
  116. Add to Windsurf's MCP configuration file:
  117. ```json
  118. {
  119. "mcpServers": {
  120. "mermaid": {
  121. "command": "claude-mermaid"
  122. }
  123. }
  124. }
  125. ```
  126. Configuration location varies by platform:
  127. - **macOS:** `~/Library/Application Support/Windsurf/mcp.json`
  128. - **Linux:** `~/.config/windsurf/mcp.json`
  129. - **Windows:** `%APPDATA%\Windsurf\mcp.json`
  130. </details>
  131. <details>
  132. <summary><strong>Gemini CLI</strong></summary>
  133. Add to Gemini CLI's MCP configuration file (`~/.gemini/mcp.json`):
  134. ```json
  135. {
  136. "mcpServers": {
  137. "mermaid": {
  138. "command": "claude-mermaid"
  139. }
  140. }
  141. }
  142. ```
  143. Or use the Gemini CLI to configure:
  144. ```bash
  145. gemini config mcp add mermaid --command claude-mermaid
  146. ```
  147. </details>
  148. <details>
  149. <summary><strong>Other MCP Clients</strong></summary>
  150. For any MCP-compatible client, use the standard configuration:
  151. ```json
  152. {
  153. "mcpServers": {
  154. "mermaid": {
  155. "command": "claude-mermaid"
  156. }
  157. }
  158. }
  159. ```
  160. The command `claude-mermaid` should be available in your PATH after installation.
  161. **Note:** Some clients may require the full path to the executable:
  162. - Find the path: `which claude-mermaid` (Unix/macOS) or `where claude-mermaid` (Windows)
  163. - Use absolute path in config: `"command": "/path/to/claude-mermaid"`
  164. </details>
  165. ## 💡 Usage
  166. Simply ask Claude Code to create Mermaid diagrams naturally. When installed as a plugin, the built-in `mermaid-diagrams` skill provides expert guidance, best practices, and automatic workflow management.
  167. ### Basic Examples
  168. ```
  169. "Create a Mermaid diagram showing the user authentication flow"
  170. "Draw a sequence diagram for the payment process"
  171. "Generate a flowchart for the deployment pipeline"
  172. ```
  173. ### Advanced Examples
  174. **With custom formatting:**
  175. ```
  176. "Create a dark theme architecture diagram with transparent background"
  177. "Generate a forest theme flowchart and save to ./docs/flow.svg"
  178. ```
  179. **With specific output format:**
  180. ```
  181. "Create an ER diagram and save as PDF to ./docs/schema.pdf"
  182. "Save the flowchart as PNG to ./docs/flow.png"
  183. ```
  184. _Note: Browser always shows SVG for live preview, while saving to your chosen format._
  185. **Iterative refinement:**
  186. ```
  187. "Create a class diagram for the User module"
  188. // Browser opens with live preview
  189. "Add the Address and Order classes with relationships"
  190. // Diagram updates automatically in browser!
  191. ```
  192. ### Complete Example
  193. ```
  194. "Create a flowchart and save to ./docs/auth-flow.svg:
  195. graph LR
  196. A[User Login] --> B{Valid Credentials?}
  197. B -->|Yes| C[Access Granted]
  198. B -->|No| D[Access Denied]
  199. C --> E[Dashboard]
  200. D --> F[Try Again]
  201. style A fill:#e1f5ff
  202. style C fill:#d4edda
  203. style D fill:#f8d7da
  204. "
  205. ```
  206. The diagram will be saved to `./docs/auth-flow.svg` and opened in your browser with live reload enabled.
  207. ## 🔧 Tools and Parameters
  208. There are two tools exposed by the MCP server:
  209. 1. `mermaid_preview` — render and open a live preview
  210. - `diagram` (string, required) — Mermaid diagram code
  211. - `preview_id` (string, required) — Identifier for this preview session. Use different IDs for multiple concurrent diagrams (e.g., `architecture`, `flow`).
  212. - `format` (string, default `svg`) — One of `svg`, `png`, `pdf`. Live preview is available only for `svg`.
  213. - `theme` (string, default `default`) — One of `default`, `forest`, `dark`, `neutral`.
  214. - `background` (string, default `white`) — Background color. Examples: `transparent`, `white`, `#F0F0F0`.
  215. - `size` (number, default `800`) — Maximum diagram width or height in pixels.
  216. - `width`, `height` (number, deprecated) — Accepted for compatibility; the larger value is used as `size`.
  217. - `scale` (number, default `2`) — Scale factor for higher quality output.
  218. 2. `mermaid_save` — save the current live diagram to a path
  219. - `save_path` (string, required) — Destination path (e.g., `./docs/diagram.svg`).
  220. - `preview_id` (string, required) — Must match the `preview_id` used in `mermaid_preview`.
  221. - `format` (string, default `svg`) — One of `svg`, `png`, `pdf`. If the live working file for this format doesn’t exist yet, it is rendered on demand before saving.
  222. ## 🎯 How Live Reload Works
  223. 1. **First render:** Opens diagram in browser at `http://localhost:3737/{preview_id}`
  224. 2. **Make changes:** Edit the diagram through Claude Code
  225. 3. **Auto-refresh:** Browser detects changes via WebSocket and reloads
  226. 4. **Status indicator:** Green dot = connected, Red dot = reconnecting
  227. The live server uses ports 3737-3747 and automatically finds an available port.
  228. ### Live Preview Controls
  229. - **Pan:** Click and drag the diagram to move it around
  230. - **Zoom:** Use browser zoom (Ctrl/Cmd + +/- or pinch-to-zoom on trackpad)
  231. - **Reset Position:** Click the ⊙ button in the status bar to recenter the diagram
  232. - **Export:** Click the ⬇ button to download as SVG or PNG
  233. ### Notes
  234. - Live preview is available for `svg` format only; PNG/PDF are rendered without live reload.
  235. - For sequence diagrams, Mermaid does not support `style` directives inside `sequenceDiagram`.
  236. ## 🖥️ Standalone server
  237. You can start the preview server without an AI agent using the `--serve` flag:
  238. ```bash
  239. claude-mermaid --serve
  240. ```
  241. This opens the diagram gallery in your browser with all previously rendered diagrams. Useful for browsing and exporting diagrams outside of a Claude Code session.
  242. ## 🛠️ Development
  243. ```bash
  244. # Install dependencies
  245. npm install
  246. # Build the project
  247. npm run build
  248. # Run tests
  249. npm test
  250. # Watch mode for development
  251. npm run dev
  252. # Start the MCP server directly
  253. npm start
  254. ```
  255. ## 📝 Troubleshooting
  256. **Error: Cannot find package 'puppeteer':**
  257. This is a rare environment-specific issue. Try these solutions:
  258. 1. **Install claude-mermaid globally**:
  259. ```bash
  260. npm install -g claude-mermaid
  261. ```
  262. 2. **Reinstall the plugin** in Claude Code:
  263. ```
  264. /plugin uninstall claude-mermaid
  265. /plugin install claude-mermaid@claude-mermaid
  266. ```
  267. **Server not connecting:**
  268. ```bash
  269. # Check if server is installed
  270. claude-mermaid -v
  271. # Reinstall if needed
  272. npm install -g claude-mermaid
  273. # Verify MCP configuration
  274. claude mcp list
  275. ```
  276. **Permission denied error:**
  277. ```bash
  278. # Make sure the binary is executable
  279. chmod +x $(which claude-mermaid)
  280. ```
  281. **Port already in use:**
  282. - The server uses ports 3737-3747
  283. - It will automatically find an available port
  284. - Check if another process is using these ports: `lsof -i :3737-3747`
  285. **Diagrams not rendering or live reload not working:**
  286. The server logs to `~/.config/claude-mermaid/logs/`:
  287. - `mcp.log` - Tool requests and diagram rendering
  288. - `web.log` - HTTP/WebSocket connections and live reload
  289. Enable debug logging in your MCP config:
  290. ```json
  291. {
  292. "mcpServers": {
  293. "mermaid": {
  294. "command": "claude-mermaid",
  295. "env": {
  296. "CLAUDE_MERMAID_LOG_LEVEL": "DEBUG"
  297. }
  298. }
  299. }
  300. }
  301. ```
  302. Then check the logs:
  303. ```bash
  304. # View MCP operations
  305. tail -f ~/.config/claude-mermaid/logs/mcp.log
  306. # View WebSocket connections
  307. tail -f ~/.config/claude-mermaid/logs/web.log
  308. ```
  309. Available log levels: `DEBUG`, `INFO` (default), `WARN`, `ERROR`, `OFF`
  310. ## 🤝 Contributing
  311. Contributions are welcome! Please feel free to submit a Pull Request.
  312. ## 📄 License
  313. MIT - see [LICENSE](LICENSE) file for details
  314. ## 🔗 Links
  315. - [GitHub Repository](https://github.com/veelenga/claude-mermaid)
  316. - [npm Package](https://www.npmjs.com/package/claude-mermaid)
  317. - [Claude Code Documentation](https://docs.claude.com/claude-code)
  318. - [Mermaid Documentation](https://mermaid.js.org/)
  319. ## 👀 See Also
  320. If you like this project, you might also be interested in
  321. - [preview-skills](https://github.com/veelenga/preview-skills) — preview skills for visualizing files in the browser (markdown, csv, json, mermaid and more)
  322. ## Hosted deployment
  323. A hosted deployment is available on [Fronteir AI](https://fronteir.ai/mcp/veelenga-claude-mermaid).

Ratings and comments

Sign in to rate this skill.

Sign in

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