mermaid

The Mermaid MCP server provides a lightweight pipeline that can analyze either a local project folder or a remote GitHub repository and produce Mermaid diagrams rendered to PNGs via Kroki. It exposes three core tools under the server: list_files to gather relevant source files, read_file to fetch file contents with a safe length limit, and render_mermaid to convert Mermaid text into an image and save it to disk. This setup is particularly useful for quickly visualizing project structures, dependencies, or flow between components while keeping security boundaries intact by restricting local file access to PROJECT_ROOT.

To use the server, first start it with the appropriate Python command and ensure environment variables are set (PROJECT_ROOT, KROKI_BASE_URL, KROKI_TIMEOUT, DIAGRAM_OUT_DIR, MAX_FILE_CHARS). Once running, you can invoke list_files to fetch a filtered list of files from either a local directory or a GitHub repo, then use read_file to retrieve file contents for those files, and finally craft a Mermaid diagram with render_mermaid to render and persist a PNG image via Kroki. The output PNG will be saved to PROJECT_ROOT/DIAGRAM_OUT_DIR with a filesystem-safe filename derived from an optional title. This workflow supports iterative exploration of large codebases with clear, visual representations.

Example usage flow: use list_files with source: "local" to discover Python files, feed relevant paths to read_file to obtain their contents, build a Mermaid diagram text that captures the discovered structure, and call render_mermaid with that text and an optional title to obtain an ImageContent payload and a saved PNG.

Prerequisites:

• Python 3.10+ installed on your system
• Access to install Python dependencies (via pip)
• A project directory that will serve as PROJECT_ROOT, and a writable diagrams/ directory inside it

1. Clone the repository (or ensure you have the MCP server code locally):

git clone <REPO_URL>
cd <REPO_DIR>

2. Create a Python virtual environment and install runtime dependencies (from the project root):

python -m venv .venv
source .venv/bin/activate        # macOS/Linux
# Windows: .venv\Scripts\activate.bat
pip install .[dev]

3. Configure environment variables (examples shown; adjust to your environment):

export PROJECT_ROOT=/path/to/project/root
export KROKI_BASE_URL=https://kroki.io
export KROKI_TIMEOUT=20
export DIAGRAM_OUT_DIR=diagrams
export MAX_FILE_CHARS=200000

4. Run the server (stdio):

python src/server/server.py

5. Optional: verify server starts and exposes the expected MCP endpoints/tools (list_files, read_file, render_mermaid) via standard I/O or client configuration.

Tips and considerations:

• Ensure PROJECT_ROOT points to a directory with appropriate read permissions and where diagrams will be saved to DIAGRAM_OUT_DIR.
• The DIAGRAM_OUT_DIR path is relative to PROJECT_ROOT. It must exist or be creatable by the server.
• MAX_FILE_CHARS helps prevent large files from consuming excessive memory; adjust according to your project scale.
• If using GitHub sources, you can leverage GITHUB_TOKEN to increase rate limits; configure in the environment if needed.
• KROKI_BASE_URL and KROKI_TIMEOUT control how the Mermaid rendering is performed; ensure network access and endpoint availability.
• Security: local reads are restricted to PROJECT_ROOT to minimize exposure; always validate and sanitize inputs when constructing Mermaid diagrams to avoid accidental leakage of internal paths.
• If you encounter SSL or verification issues with HTTP requests, adjust HTTP_VERIFY as needed in your environment.