mermaid

The Mermaid MCP Server is a Python-based MCP server that validates Mermaid diagrams by wrapping the Mermaid CLI. It takes Mermaid diagram text, runs the Mermaid CLI to check syntax, and returns a structured result indicating whether the diagram is valid. When requested, it can also render the diagram to a PNG image and return that image as a base64-encoded string for visual verification. This makes it easy for LLMs to programmatically validate diagrams, surface precise error messages, and optionally incorporate rendered previews into responses.

To use the server, deploy it via uv (as shown in the configuration example) or your preferred MCP client that can call an MCP server. The server exposes a tool-like interface (validate_mermaid_diagram) that accepts diagram_text and an optional return_image flag. By default, the server prioritizes validation results to minimize message size, but you can enable image rendering when you need a visual check of the diagram rendering.

Prerequisites

• Node.js and npm (required to install Mermaid CLI and related tooling)
• Python 3.9+ with uv (for running the MCP server)

Step-by-step installation

1. Install Mermaid CLI globally (required for validation and rendering): npm install -g @mermaid-js/mermaid-cli

2. Verify Mermaid CLI installation: npx @mermaid-js/mermaid-cli --version

3. Install Python dependencies (if a virtual environment is used): uv install

4. Clone this repository ( Mermaid MCP Server ) and install Python dependencies if a requirements.txt exists (or follow project-specific setup): git clone https://github.com/andrewginns-mermaid-mcp-server.git cd mermaid_mcp_server uv sync

5. Run the MCP server (example): uv run mermaid_mcp_server.py

6. Configure your MCP client to point to the server (see Configuration in README) and ensure Node.js/Mermaid CLI are accessible in your environment.

Notes and tips:

• Ensure Node.js and Mermaid CLI are installed before starting the server, even if you only use the server component.
• The MCP_TRANSPORT environment variable should typically be set to 'stdio' when using standard input/output communication with your MCP client.
• When using validate_mermaid_diagram, consider withholding the base64 image by default to keep context length low; set return_image=true only when you need a rendered preview.
• If you encounter permission or path issues, ensure the path to mermaid_mcp_server.py is absolute and the server has read/write access to temporary files created during validation.