READMEmain

Kroki-MCP

Kroki-MCP is a command-line tool and MCP integration for converting textual diagrams (e.g., PlantUML, Mermaid) into images using a Kroki backend. It supports both local and remote Kroki servers, with flexible configuration and multiple output formats.

Features

Modes:
- SSE: Streams results using Server-Sent Events.
- STDIO (default): Reads diagram code from stdin and outputs to stdout.
Output Formats: Supports svg (default) and png. SVG is returned as markup text, normalized to scale and stay transparent when rendered inline in chat (e.g., Claude Desktop); PNG is returned as an image.
Kroki Server: Configurable backend host (default: https://kroki.io).
Extensible: Easily add support for more diagram types and output formats.
MCP Integration: Exposes diagram conversion as an MCP tool using github.com/mark3labs/mcp-go.

Usage

# Default (SSE mode, PNG, default Kroki host)
kroki-mcp

# Specify output format
kroki-mcp --format svg

# Use STDIO mode
kroki-mcp --mode stdio --format svg

# Specify a custom Kroki server
kroki-mcp --kroki-host http://localhost:8000

Configuration

Option	Description	Type	Default
`--host`, `-h`	Server host address	string	`localhost`
`--port`, `-p`	Server port	int	`5090`
`--mode`, `-m`	Operation mode (`sse` or `stdio`)	string	`stdio`
`--format`, `-f`	Output format (`png`, `svg`)	string	`png`
`--kroki-host`	Kroki server URL	string	`https://kroki.io`
`--log-level`	Log level (`debug`, `info`, `warn`, `error`)	string	`info`
`--log-format`	Log format (`text` or `json`)	string	`text`

Project Structure

kroki-mcp/
├── cmd/
│   └── kroki-mcp/           # Main CLI and MCP server entry point
├── internal/
│   ├── kroki/               # Kroki client logic (HTTP, formats)
│   ├── config/              # Configuration management (flags, env, files)
│   └── mcp/                 # MCP tool/server integration
├── test/                    # Unit and integration tests
├── Dockerfile               # Docker build file
├── docker-compose.yml       # Docker Compose for dev environment
├── go.mod                   # Go module definition
├── README.md                # Project documentation
└── .gitignore               # Git ignore file

Implementation Steps

Scaffold Go project.
Implement CLI with default SSE mode, format flags.
Implement Kroki client supporting all formats.
Implement SSE and STDIO modes.
Integrate with mcp-go for MCP tool support.
Add error handling and tests.
Document usage.

Example: Running as an MCP Server

To run Kroki-MCP as an MCP server from source:

go run github.com/utain/kroki-mcp/cmd/kroki-mcp@latest --mode sse --format png --kroki-host https://kroki.io

You can configure the MCP server in your MCP configuration file as follows:

{
  "mcpServers": {
    "kroki-mcp": {
      "command": "go",
      "args": [
        "run",
        "github.com/utain/kroki-mcp/cmd/kroki-mcp@latest",
        "-m", "stdio",
        "-f", "png",
        "--kroki-host", "https://kroki.io"
      ]
    }
  }
}

Development with Docker

You can use Docker and docker-compose for local development and testing.

Build and Run with Docker

docker build -t kroki-mcp .
docker run --rm -it kroki-mcp --help

Using docker-compose (with local Kroki server)

docker-compose up --build

This will start both a Kroki server and the kroki-mcp service.
kroki-mcp will connect to the Kroki server at http://kroki:8000.

Contributing

Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

Changelog

See CHANGELOG.md for release history.

Related Projects

License

This project is licensed under the MIT License.

kroki-mcp