GittyBurstein/mermaid-mcp-server

**Mermaid MCP Server** is an MCP server that helps agents turn large codebases (local folders or GitHub repositories) into **Mermaid diagrams** and render them as **PNG images** via **Kroki**, enabling fast, reliable understanding of a project’s structure and flow.
Why this server
When working with a new codebase, it’s easy to lose time jumping between folders and files. This server provides a clean, tool-based workflow for agents to **discover**, **read**, and **visualize** a project — without guessing paths or inventing structure.
Key features
- **Local + GitHub sources**: analyze either a local project folder or a remote repository.
- **Agent-friendly pipeline**: list_files → read_file → generate Mermaid → render_mermaid.
- **Safe local access boundary**: local reads are restricted to PROJECT_ROOT.
- **Configurable limits**: control max file size (MAX_FILE_CHARS) and output directory (DIAGRAM_OUT_DIR).
- **Portable output**: rendered diagrams are returned as image content and also saved as PNG files.
It exposes three tools:
| Tool | Description |
|------|-------------|
| list_files | List files from a local folder or a GitHub repo (supports root + glob filtering). |
| read_file | Read file contents (local or GitHub) with a configurable max length. |
| render_mermaid | Render Mermaid text via Kroki and return ImageContent (also saves to disk). |
1) list_files
Returns a list of files for a given source (local / github) with root + glob filtering.
Parameters
- source: "local" or "github"
- root: default "."
- glob: default "**/*"
- repo_url: required when source="github"
- ref: default "main"
- recursive: default true
Example (local)
Example (github)
2) read_file
Reads file contents (local or GitHub) with a length limit.
Parameters
- source: "local" or "github"
- path: required
- repo_url: required when source="github"
- ref: default "main"
- max_chars: default MAX_FILE_CHARS
Example (local)
Example (github)
3) render_mermaid
Accepts Mermaid text, renders it to a PNG via Kroki, returns ImageContent, and saves the file to disk.
Parameters
- mermaid: required (string) — the Mermaid diagram source text
- title: optional (string) — used to derive the output filename (will be sanitized)
Returns
- ImageContent containing the rendered PNG bytes
- Also writes the PNG file to PROJECT_ROOT/DIAGRAM_OUT_DIR/ .png
Behavior
- If mermaid is empty → error
- File is saved under DIAGRAM_OUT_DIR (inside PROJECT_ROOT)
- Output path: the image is saved to PROJECT_ROOT/DIAGRAM_OUT_DIR/ .png (default output dir: ./diagrams/).
- Filename: derived from title (sanitized to be filesystem-safe). If title is missing, a default name is used.
- Name collisions: if .png already exists, it is overwritten.
Example
Requirements
- Python 3.10+ (recommended)
- Internet access (for Kroki, and for GitHub when using github source)
---
Project structure
For architecture details, see: ARCHITECTURE.md
Docker (optional)
Build and run with Docker (example):
---
Installation & Setup
1) Clone the repo
2) Create a venv + install dependencies
Windows (PowerShell):
Windows (CMD):
macOS/Linux:
> This installs runtime dependencies and development extras (tests).
3) Configuration (Environment Variables)
You can set env vars in your shell OR in the MCP client config that launches the server.
Required / Recommended
| Variable | Description | Used by |
|---|---|---|
| PROJECT_ROOT | Local project root that the server is allowed to access (security boundary) | local_source |
| KROKI_BASE_URL | e.g. https://kroki.io | render_mermaid |