kroki-mcp

MCP server wrapping a self-hosted Kroki instance, exposing diagram rendering as MCP tools.

Supports 29+ diagram types including PlantUML, Mermaid, GraphViz, D2, DBML, ERD, and more. See Kroki's diagram support list for the full list.

Quick start

# Set the Kroki instance URL
export KROKI_MCP_KROKI_URL=http://localhost:8000

# Install and run (stdio transport)
pip install kroki-mcp[mcp]
kroki-mcp serve

Configuration

Variable	Required	Default	Description
`KROKI_MCP_KROKI_URL`	Yes	—	URL of your self-hosted Kroki instance (e.g. `http://localhost:8000`)
`KROKI_MCP_READ_ONLY`	No	`true`	Disable write tools
`KROKI_MCP_LOG_LEVEL`	No	`INFO`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`KROKI_MCP_SERVER_NAME`	No	`kroki-mcp`	Server name shown to clients
`KROKI_MCP_INSTRUCTIONS`	No	(dynamic)	System instructions for LLM context

Tools

`render_diagram`

Render a diagram using Kroki.

Parameters:

diagram_type — diagram language (e.g. "plantuml", "mermaid", "graphviz")
source — diagram source code
output_format — "svg" (default) or "png"
as_base64 — when true and format is PNG, return base64 string instead of MCP Image

`list_diagram_types`

List all supported diagram types and their output formats. Returns a JSON array.

Resources

`kroki://health`

Check if the Kroki instance is reachable. Returns JSON with status ("ok" or "unreachable").

Prompts

`diagram_helper`

Get syntax guidance and a basic example for a given diagram type, plus instructions to use render_diagram.

Parameter: diagram_type — e.g. "mermaid", "plantuml", "graphviz"

Authentication

The server supports bearer token and OIDC auth for HTTP transport:

Variable	Description
`KROKI_MCP_BEARER_TOKEN`	Static bearer token
`KROKI_MCP_BASE_URL`	Public server URL — required for OIDC (e.g. `https://mcp.example.com`)
`KROKI_MCP_OIDC_CONFIG_URL`	OIDC discovery endpoint
`KROKI_MCP_OIDC_CLIENT_ID`	OIDC client ID
`KROKI_MCP_OIDC_CLIENT_SECRET`	OIDC client secret
`KROKI_MCP_OIDC_JWT_SIGNING_KEY`	JWT signing key — required on Linux/Docker to survive restarts

See Authentication guide for full setup details.

Docker

export KROKI_MCP_KROKI_URL=http://kroki:8000
docker compose up -d

See Docker deployment for volumes, UID/GID, and Traefik setup.

Development

uv sync --all-extras
uv run pytest
uv run ruff check src/ tests/
uv run mypy src/

License

MIT

Kroki MCP