MCP Mermaid (Fork)

This is a fork of hustcc/mcp-mermaid that adds file output capabilities.

Generate mermaid diagram and chart with AI MCP dynamically. This fork adds the ability to save generated diagrams to files. Also you can use mcp-server-chart to generate chart, graph, map.

✨ Features

• Fully support all features and syntax of Mermaid.
• Support configuration of backgroundColor and theme, enabling large AI models to output rich style configurations.
• Support exporting to png, svg, and mermaid formats, with validation for Mermaid to facilitate the model's multi-round output of correct syntax and graphics.
• NEW: Save generated diagrams to files with configurable output paths
• NEW: Auto-generate filenames when saving to directories
• NEW: Choose between returning content or just save confirmation

🤖 Usage

To use with Desktop APP, such as Claude, VSCode, Cline, Cherry Studio, and so on, add the MCP server config below. On Mac system:

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

On Window system:

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

Also, you can use it on aliyun, modelscope, glama.ai, smithery.ai or others with HTTP, SSE Protocol.

🚰 Run with SSE or Streamable transport

Install the package globally.

npm install -g @falldownthesystem/mcp-mermaid

Run the server with your preferred transport option:

# For SSE transport (default endpoint: /sse)
mcp-mermaid -t sse

# For Streamable transport with custom endpoint
mcp-mermaid -t streamable

Then you can access the server at:

• SSE transport: http://localhost:3033/sse
• Streamable transport: http://localhost:3033/mcp

🎮 CLI Options

You can also use the following CLI options when running the MCP server. Command options by run cli with -h.

MCP Mermaid CLI

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

📁 File Output Features (NEW)

This fork adds two new optional parameters to the generate_mermaid_diagram tool:

outputPath (string, optional)

• File path where the generated diagram should be saved
• Can be absolute or relative path
• If path is a directory, filename will be auto-generated with timestamp
• If path has no extension, it's treated as a directory

saveOnly (boolean, optional, default: true)

• true: Save file and return only confirmation message with file path
• false: Save file AND return the generated content (backward compatible)

Usage Examples

Save to specific file:

{
  "mermaid": "graph TD; A-->B;",
  "outputPath": "/path/to/diagram.png",
  "saveOnly": true
}

Save to directory with auto-generated filename:

{
  "mermaid": "graph TD; A-->B;",
  "outputPath": "/path/to/directory/",
  "outputType": "svg"
}

Save file but also return content:

{
  "mermaid": "graph TD; A-->B;",
  "outputPath": "./diagrams/",
  "saveOnly": false
}

🔨 Development

Install dependencies:

npm install

Build the server:

npm run build

Start the MCP server:

npm run start

📄 License

MIT@hustcc.