Kroki MCP Diagram Generator

A Python project that turns natural-language prompts into rendered diagrams using a LangGraph workflow, an LLM, and the Kroki rendering engine. It can generate diagram source, validate it against Kroki, and save the final SVG output to disk for direct viewing.

Overview

This project combines three main components:

• A Kroki HTTP client for sending diagram source to Kroki

• A FastMCP server that exposes rendering tools to AI agents

• A LangGraph agent that classifies the request, generates DSL, validates it, and repairs it if needed

The goal is to make diagram generation feel like a tool-backed AI workflow rather than a standalone script.

Related MCP server: Excalidraw MCP Server

Architecture

flowchart LR
    A[User Prompt] --> B[LangGraph Agent]
    B --> C[Intent Classification]
    C --> D[DSL Generation]
    D --> E[Kroki Validation / Render]
    E -->|Failure| F[Self Repair]
    F --> E
    E -->|Success| G[SVG File Output]

Project Structure

kroki_mcp/
├── agent.py             # LangGraph workflow for generating and validating diagrams
├── kroki_client.py     # HTTP client for Kroki rendering requests
├── mcp_server.py       # FastMCP server exposing diagram tools
├── requirements.txt    # Python dependencies
├── .env.example        # Example environment variables
└── output/             # Generated SVG files

Main Components

1. Agent Workflow

The agent in agent.py uses a state machine to:

1. Interpret the user's request

2. Choose the most appropriate diagram engine

3. Generate diagram source in the relevant DSL

4. Send it to Kroki for rendering

5. Retry and self-repair if the syntax is invalid

It uses:

• LangGraph for orchestration

• LangChain message objects for prompts

• OpenAI-compatible LLM endpoints via langchain-openai

2. Kroki Client

The client in kroki_client.py handles:

• payload compression and encoding

• HTTP GET/POST requests to Kroki

• SVG rendering requests

It supports the public Kroki endpoint at https://kroki.io by default.

3. MCP Server

The FastMCP server in mcp_server.py exposes tools such as:

• render_diagram

• validate_diagram

• get_diagram_capabilities

These tools can be used by AI agents or MCP-compatible clients.

Supported Diagram Types

The workflow can target several diagram engines, including:

• mermaid

• plantuml

• d2

• c4plantuml

• graphviz

• erd

• bpmn

Dependencies

The project uses:

• fastmcp

• httpx

• langgraph

• langchain-core

• langchain-openai

• pydantic

• python-dotenv

See requirements.txt for the exact versions.

Environment Setup

Create a local environment file named .env in the project root.

Example:

KROKI_HOST=https://kroki.io
API_KEY=your_api_key_here
BASE_URL=your_base_url_here
MODEL_NAME=your_model_name_here

The agent will fall back to local placeholder content if the LLM configuration is not available.

Installation

Create and activate a virtual environment:

python -m venv .venv
.venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Running the Agent

Run:

python agent.py

If rendering succeeds, the script will write an SVG file to the output directory.

Example Flow

sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Kroki

    User->>Agent: Give a diagram request
    Agent->>LLM: Choose diagram type
    LLM-->>Agent: Selected engine
    Agent->>LLM: Generate DSL
    LLM-->>Agent: Diagram source
    Agent->>Kroki: Render SVG
    Kroki-->>Agent: Rendered SVG
    Agent->>User: Save SVG file

Output

The generated file is saved in the output folder as an SVG, for example:

• output/diagram_mermaid.svg

This file can be opened directly in a browser or any SVG-compatible viewer.

Notes

• The project is designed for experimentation and integration with AI agents.

• It is not yet a full production deployment system, but it provides the core building blocks for one.

• For real-world use, you may want to add authentication, logging, caching, and persistent storage.

Future Improvements

Possible enhancements include:

• support for PNG and PDF export

• richer error handling and logging

• database-backed history and diagram storage

• a web UI for uploading prompts and viewing diagrams

• deployment as a service or container