Mermaid
A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images.
What is Mermaid?
Mermaid is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to model context protocol (mcp) server that converts mermaid diagrams to png images.
A Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- generate
Use Cases
Maintainer
Works with
Installation
NPM
npx -y @peng-shawn/mermaid-mcp-serverManual Installation
npx -y @peng-shawn/mermaid-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Mermaid
The Mermaid MCP Server allows AI assistants to render Mermaid diagram syntax into PNG or SVG image files on demand, bridging the gap between text-based diagram code and visual output. It exposes a single generate tool that accepts any valid Mermaid diagram — flowcharts, sequence diagrams, state machines, ER diagrams, Gantt charts, and more — and returns either an inline image (for clients that support it) or saves the file to disk. Developers and technical writers can ask Claude to design and immediately visualize system architectures, data flows, and workflows without leaving their AI assistant session.
Prerequisites
- Node.js 18+ installed on your system
- npx available (bundled with Node.js)
- An MCP-compatible client such as Claude Desktop or Cursor
- For Cursor or clients that do not display images inline: a writable folder for saving output files
No installation required — use npx
The server is published on npm as @peng-shawn/mermaid-mcp-server and can be run directly with npx without a separate install step.
npx -y @peng-shawn/mermaid-mcp-serverAdd the server to Claude Desktop configuration
Edit your claude_desktop_config.json to register the Mermaid MCP server. No environment variables are required for Claude Desktop's default inline-image mode.
{
"mcpServers": {
"mermaid": {
"command": "npx",
"args": ["-y", "@peng-shawn/mermaid-mcp-server"]
}
}
}Configure for Cursor or disk-save mode
For clients that do not support inline images (Cursor, Cline), set CONTENT_IMAGE_SUPPORTED=false. The generate tool will then require name and folder parameters and save the file to disk.
{
"mcpServers": {
"mermaid": {
"command": "npx",
"args": ["-y", "@peng-shawn/mermaid-mcp-server"],
"env": {
"CONTENT_IMAGE_SUPPORTED": "false"
}
}
}
}Restart your MCP client
Restart Claude Desktop or your MCP client so it loads the new server. The generate tool will appear in the tool list.
Test diagram generation
Ask Claude to draw a simple flowchart to confirm the tool is working and images are rendering correctly.
Mermaid Examples
Client configuration
Standard claude_desktop_config.json entry for the Mermaid MCP server with inline image support enabled (default behavior).
{
"mcpServers": {
"mermaid": {
"command": "npx",
"args": ["-y", "@peng-shawn/mermaid-mcp-server"]
}
}
}Prompts to try
Example prompts that trigger the Mermaid generate tool for various diagram types.
- "Draw a flowchart showing a user authentication flow with success and failure paths."
- "Create a sequence diagram of how an HTTP request moves through a load balancer, API gateway, and microservice."
- "Generate an ER diagram for a blog database with users, posts, comments, and tags tables."
- "Draw a Gantt chart for a 4-week software sprint with planning, development, testing, and release phases."
- "Create a state diagram showing the lifecycle of an order from placed to delivered, with cancel and refund states."Troubleshooting Mermaid
generate tool call fails with a Puppeteer or Chrome error
The server uses Puppeteer to render diagrams and bundles its own Chromium. On Linux servers or Docker containers, install Chrome dependencies: apt-get install -y libnss3 libatk-bridge2.0-0 libx11-xcb1 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libasound2. Alternatively, set PUPPETEER_EXECUTABLE_PATH to an existing Chrome binary.
Diagram is generated but no image appears in Claude Desktop
Ensure CONTENT_IMAGE_SUPPORTED is not set to false in your config. The default (true) returns the image inline. If the response shows text instead of an image, your client version may not support image content — switch to disk-save mode and open the file manually.
Saving to disk fails with 'folder parameter required'
When CONTENT_IMAGE_SUPPORTED=false, the generate tool requires both name (filename without extension) and folder (absolute path to an existing directory) parameters. Include them in your prompt: "Save the diagram as 'arch-diagram' in /Users/yourname/diagrams/".
Frequently Asked Questions about Mermaid
What is Mermaid?
Mermaid is a Model Context Protocol (MCP) server that model context protocol (mcp) server that converts mermaid diagrams to png images. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Mermaid?
Install via npm with the command: npx -y @peng-shawn/mermaid-mcp-server. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with Mermaid?
Mermaid works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Mermaid free to use?
Yes, Mermaid is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Mermaid Alternatives — Similar Developer Tools Servers
Looking for alternatives to Mermaid? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Mermaid in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Mermaid?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.