mcp-mermaid

MCP Mermaid supports all Mermaid syntax and features, including configuration for backgroundColor and theme.

It supports exporting diagrams in the following formats:

• base64
• svg
• mermaid
• file (Use outputType: "file" to automatically save PNG diagrams to disk for AI agents)
• svg_url (Remote-friendly)
• png_url (Remote-friendly, uses public mermaid.ink links)

To integrate MCP Mermaid with desktop applications like Claude, VSCode, Cline, or Cherry Studio, add the server configuration to your MCP settings. The configuration differs based on your operating system.

Mac Configuration:

{
  "mcpServers": {
    "mcp-mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ]
    }
  }
}

Windows Configuration:

{
  "mcpServers": {
    "mcp-mermaid": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-mermaid"
      ]
    }
  }
}

Use Docker to run the MCP Mermaid server in a containerized environment.

# Pull the latest image
docker pull susuperli/mcp-mermaid:latest

# Run with SSE transport (default port 3033)
docker run -p 3033:3033 susuperli/mcp-mermaid:latest --transport sse

# Run with streamable transport (port 1122)
docker run -p 1122:1122 susuperli/mcp-mermaid:latest --transport streamable --port 1122

You can run the MCP Mermaid server using different transport protocols.

Global Installation

First, install the package globally:

npm install -g mcp-mermaid

Then, run the server using the -t flag:

• SSE transport (default endpoint: /sse):

  mcp-mermaid -t sse

- **Streamable transport** (custom endpoint):
  ```bash
mcp-mermaid -t streamable

Local Development

If you are running from the source code:

npm install
npm run build

# Start SSE transport on port 3033
npm run start:sse

# Start Streamable transport on port 1122
npm run start:streamable

Access Points

• SSE: http://localhost:3033/sse
• Streamable: http://localhost:1122/mcp (local) or http://localhost:3033/mcp (global)

When calling the mermaid tool via the MCP server, you can specify an outputType to determine the format of the response. Supported values include:

• mermaid: Returns the raw mermaid text.
• svg: Returns the raw SVG string.
• svg_url: Returns a URL pointing to an SVG version of the diagram (via Mermaid Ink).
• png_url: Returns a URL pointing to a PNG version of the diagram (via Mermaid Ink).
• file: Saves the diagram as a .png file in the current working directory and returns the local file path.
• base64 (default): Returns the diagram as a base64 encoded PNG image in the MCP response content.

When running the MCP Mermaid CLI directly, you can use the following options to configure the server behavior. Use -h to show the help message.

Options:
  --transport, -t  Specify the transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
  --port, -p       Specify the port for SSE or streamable transport (default: 3033)
  --endpoint, -e   Specify the endpoint for the transport:
                    - For SSE: default is "/sse"
                    - For streamable: default is "/mcp"
  --help, -h       Show this help message

Use createMermaidInkUrl to generate a public URL that renders Mermaid diagram definitions via the mermaid.ink service. The function compresses the diagram definition using deflate and encodes it into a Base64URL format compatible with the pako endpoint.

Parameters:

• mermaid: The raw Mermaid diagram string.
• variant: The output format, either 'svg' or 'img'.
• theme: The Mermaid theme to apply (e.g., 'default'). Defaults to 'default'.
• look: The visual style of the diagram. Use 'classic' for standard rendering or 'handDrawn' for a sketch-style look. Defaults to 'classic'.

import { createMermaidInkUrl } from './src/utils/mermaidUrl';

const mermaidCode = 'graph TD; A-->B;';
const url = createMermaidInkUrl(mermaidCode, 'svg', 'forest', 'handDrawn');
// Returns a URL like: https://mermaid.ink/svg/pako:eyJjb2RlIjoi... 

Use runStdioServer() to start the MCP server using standard input/output (stdio) transport. This is the standard method for local MCP integrations where the client communicates with the server process directly via pipes.

import { runStdioServer } from './src/server';

await runStdioServer();

Use createServer() to instantiate a pre-configured McpServer instance specifically for mermaid diagram generation. This instance includes the necessary tool handlers for rendering diagrams via the tool definition. It is the foundation for running the server using different transport methods (Stdio, SSE, or HTTP Streamable).

import { createServer } from './src/server';

const server = createServer();
// The server is now ready to be passed to a transport starter function.

The renderMermaid function converts Mermaid diagram syntax into a rendered image (via mermaid-isomorphic). It accepts the diagram string and optional configuration for theme, background color, and visual style.

Parameters:

• mermaid (string): The Mermaid diagram syntax to render.
• theme (string, default: "default"): The Mermaid theme to apply.
• backgroundColor (string, default: "white"): The background color for the SVG.
• look ("classic" | "handDrawn", default: "classic"): The visual style of the diagram.

Returns:

• Promise<RenderResult>: A promise that resolves to the rendered result (typically containing the image data/path).

import { renderMermaid } from './path-to-utils/render';

const mermaidSyntax = 'graph TD; A-->B;';
const result = await renderMermaid(mermaidSyntax, 'forest', 'transparent', 'handDrawn');