list_filesLABSCO SUMMARY
Discover, read, draw — in that order.
The value is in the order of operations. An agent asked to diagram a project usually invents the structure; here it has to list the files and read them before it can draw, so the diagram describes what is on disk. The read boundary is worth setting deliberately, since the configured project root is what stops a glob from wandering up the filesystem.
What it is
A three-step pipeline for diagramming a project: list the files that match, read the ones that matter, then render the Mermaid the model writes into an image through Kroki. Local reads are confined to a configured project root, and GitHub repositories are read by URL and ref.
What you get
- Files listed from a local folder or a GitHub repository, narrowed by root and glob and optionally recursive
- File contents read from either source, up to a configurable character limit
- Mermaid text rendered through Kroki, returned as image content and saved to disk as a PNG
- Local reads confined to the configured project root, with the output directory and maximum file size configurable
Requirements
A project root the server is allowed to read, and network access for the Kroki render and for any GitHub source. Reads outside the configured root are refused.
Setup effort
Build from source — git clone https://github.com/GittyBurstein/mermaid-mcp-server.git
USE CASES
01
Understanding a repository you just cloned
List what is actually in it, read the files that carry the structure, and get an architecture diagram back as a picture rather than as a paragraph.
02
Diagramming a project you have not checked out
Point it at a GitHub URL and ref and it reads from there directly, so an evaluation does not have to start with a clone.
03
Documenting a flow that keeps being explained verbally
Read the modules involved, render the sequence as Mermaid, and get a PNG saved to disk that can go straight into the README.
04
Diagramming one layer instead of everything
Glob filtering narrows the pass to a subdirectory or a file type, which is what keeps a large repository's diagram readable.
05
Rendering a diagram you already wrote
Hand it Mermaid text you have on hand and get the image back and saved, with no local rendering toolchain to install.
3 tools
Listed in project docs. Your client may show a different list.
read_filerender_mermaidBEFORE YOU INSTALL
What to know first
Tools you get
3 tools named in the project's documentation. render_mermaid writes PNGs to PROJECT_ROOT/DIAGRAM_OUT_DIR and silently overwrites existing files. GITHUB_TOKEN is optional, recommended to avoid GitHub rate limits.
Requires
Python 3.10+
INSTALLATION
Connect your client
You clone this one yourself.
Server setup
TERMINAL
git clone https://github.com/GittyBurstein/mermaid-mcp-server.git
cd mermaid-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install ".[dev]"MCP Clients
Docker
DOCKER · TERMINAL
docker build -t mermaid-mcp:latest .
docker run --rm -it \
-v "$PWD":/app \
-e PROJECT_ROOT=/app \
-e KROKI_BASE_URL=https://kroki.io \
-e KROKI_TIMEOUT=20 \
-e DIAGRAM_OUT_DIR=diagrams \
mermaid-mcp:latestClaude Desktop — Windows
CLAUDE DESKTOP — WINDOWS · JSON
{
"mcpServers": {
"mermaid-mcp": {
"command": "C:\\Users\\<YOUR_USERNAME>\\<YOUR_PATH_TO_REPO>\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Users\\<YOUR_USERNAME>\\<YOUR_PATH_TO_REPO>\\src\\server\\server.py"
],
"env": {
"PROJECT_ROOT": "C:\\Users\\<YOUR_USERNAME>\\<YOUR_PATH_TO_REPO>",
"KROKI_BASE_URL": "https://kroki.io",
"KROKI_TIMEOUT": "20",
"DIAGRAM_OUT_DIR": "diagrams",
"MAX_FILE_CHARS": "200000"
}
}
}
}%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop — macOS
CLAUDE DESKTOP — MACOS · JSON
{
"mcpServers": {
"mermaid-mcp": {
"command": "<YOUR_PROJECT_ROOT>/.venv/bin/python",
"args": [
"<YOUR_PROJECT_ROOT>/src/server/server.py"
],
"env": {
"PROJECT_ROOT": "<YOUR_PROJECT_ROOT>",
"KROKI_BASE_URL": "https://kroki.io",
"KROKI_TIMEOUT": "20",
"DIAGRAM_OUT_DIR": "diagrams",
"MAX_FILE_CHARS": "200000"
}
}
}
}~/Library/Application Support/Claude/claude_desktop_config.json
