mermaid-mcp-server Public

. ├── README.md ├── Dockerfile ├── pyproject.toml ├── .env.example ├── .gitignore └── src/ ├── config.py # Env/config defaults ├── server/ # MCP server entrypoint │ └── server.py ├── tools/ # MCP tools (list/read/render) │ ├── list_files.py │ ├── read_file.py │ └── render_mermaid.py ├── sources/ # File sources behind one interface (Local / GitHub) │ ├── local_source.py │ ├── github_source.py │ └── source_factory.py ├── core/ # Contracts + primitives (interfaces, errors, cache, pacing, rate limiting) │ ├── interfaces.py # Source contract that shapes all implementations │ ├── models.py │ ├── errors.py │ ├── paths.py # Shared path normalization + glob semantics (incl. ) │ ├── cache.py │ ├── pacing.py │ └── rate_limiter.py ├── clients/ # External API clients (kept thin; shared policies live in core) │ ├── kroki_client.py │ └── github/ │ ├── client.py # HTTP + policy (cache/rate/pacing) │ ├── inputs.py # normalize/validate inputs │ └── refs.py # resolve refs (+ fallback) ├── resources/ # Mermaid styles and small assets └── prompts/ # Server-side canonical prompts

For architecture details, see:ARCHITECTURE.md

# build image docker build -t mermaid-mcp:latest . # run container (example, mount project root and set env vars) 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:latest

git clone <REPO_URL> cd <REPO_DIR>

python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install .[dev]

python -m venv .venv .venv\Scripts\activate.bat pip install .[dev]

python -m venv .venv source .venv/bin/activate pip install .[dev]

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.

set PROJECT_ROOT=. set KROKI_BASE_URL=https://kroki.io set KROKI_TIMEOUT=20 set DIAGRAM_OUT_DIR=diagrams set MAX_FILE_CHARS=200000

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

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.

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

- 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 toclaude_desktop_config.json

{ "mcpServers": { "mermaid-mcp": { "command": "C:\\Users\\<YOU>\\path\\to\\repo\\.venv\\Scripts\\python.exe", "args": [ "C:\\Users\\<YOU>\\path\\to\\repo\\src\\server\\server.py" ], "env": { "PROJECT_ROOT": "C:\\Users\\<YOU>\\path\\to\\repo", "KROKI_BASE_URL": "https://kroki.io", "KROKI_TIMEOUT": "20", "DIAGRAM_OUT_DIR": "diagrams", "MAX_FILE_CHARS": "200000" } } } }

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

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

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 namegenerate_mermaid_canonicaland is defined insrc/prompts/mermaid_prompt.py.

-

Client-supported prompts (recommended): If your MCP client supports server-side prompts, select the servermermaid-mcp, pick the prompt namedgenerate_mermaid_canonicalfrom 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, opensrc/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.

- The canonical prompt enforces strict tool usage and requires the canonical style resourcemermaid://styles/blue-flowchartto 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.

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