mermaid-mcp — one MCP server to diagram any project (Local/GitHub → Mermaid → PNG)

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:

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/<filename>.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/<filename>.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 <filename>.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

Optional

Example (Windows)

Example (macOS / Linux)

4) Run the server (stdio)

Server name: mermaid-mcp

Connect an MCP client (example: Claude Desktop)

Any MCP client that can launch a local stdio server can use this project. Below is an example configuration for Claude Desktop.

1) Locate Claude Desktop config

Claude Desktop stores MCP server definitions in a JSON config file.

Common locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

If the file doesn’t exist yet, create it.

2) Add this server to claude_desktop_config.json

Example (Windows):

3) Restart Claude Desktop

After saving the config file, fully close Claude Desktop and reopen it so the server is loaded.

4) Verify tools are available

Open Claude Desktop and check that the server tools appear (e.g. list_files, read_file, render_mermaid).

Using the canonical prompt

This project includes a canonical system prompt used to generate Mermaid diagrams in a consistent, tool-driven way. The prompt is registered on the MCP server under the name generate_mermaid_canonical and is defined in src/prompts/mermaid_prompt.py.

Two common ways to use it:

• Client-supported prompts (recommended): If your MCP client supports server-side prompts, select the server mermaid-mcp, pick the prompt named generate_mermaid_canonical from the prompt list, and run it as the agent's system/instruction before invoking the tools. Using the server-registered prompt ensures agents always get the latest prompt text.

• Copy & paste: If your client does not support server-side prompts, open src/prompts/mermaid_prompt.py, copy the prompt text, and paste it into the agent's system message or save it locally as a preset. Keep in mind you will need to update your local copy when the repository prompt changes.

Notes:

• The canonical prompt enforces strict tool usage and requires the canonical style resource mermaid://styles/blue-flowchart to be read and embedded unchanged into generated diagrams.

• The prompt expects the agent to follow the pipeline: list_files → read_file → generate Mermaid → render_mermaid.

Testing

Run the test suite:

End-to-end example:

This is a complete, realistic flow that demonstrates the intended pipeline: list_files → read_file → generate Mermaid → render_mermaid.

Step 1 — List files from a GitHub repo

Step 2 — Pick a small set of important files (5–12)

Example selection (you choose based on what the repo contains):

• src/server/server.py

• src/tools/list_files.py

• src/tools/read_file.py

• src/tools/render_mermaid.py

• src/core/interfaces.py

• src/clients/github/client.py

• src/clients/github/refs.py

• src/core/cache.py

• src/core/pacing.py

• src/core/rate_limiter.py

• src/clients/kroki_client.py

Step 3 — Read the chosen files

Step 4 — Generate Mermaid from what you read

Step 5 — Render Mermaid to PNG

Security & Predictable Behavior

For security and predictable behavior, see: Security boundaries

Troubleshooting

• "Missing repo_url for github source" → you forgot repo_url with source="github"

• "Missing file path" → you called read_file without path

• "Access outside project root is not allowed" → attempted to read outside PROJECT_ROOT

• "DIAGRAM_OUT_DIR must be within PROJECT_ROOT" → output dir is not inside PROJECT_ROOT

Future work (additional sources)

Next, we plan to support more input sources beyond local folders and GitHub, so the server can generate Mermaid diagrams from additional code hosts and content providers (e.g., GitLab, Bitbucket, Azure DevOps Repos, as well as ZIP archives or single files via URL).

This will build on a unified Source abstraction: each new source will implement the same contract (list_files and read_file), while the tools remain unchanged—extending support will require only adding a new source implementation and registering it in the factory.