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) andpng. 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
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.
