Home
Relevant source files
The following files were used as context for generating this wiki page:
Dokku MCP Server is a Go application that acts as an intermediary, exposing the management capabilities of a Dokku PaaS instance through the Model Context Protocol (MCP). This allows Large Language Models (LLMs) and other agentic tools (such as Cursor or Claude) to interact with and manage Dokku programmatically. The project is in its early stages of development and is not yet recommended for production use.
The server's primary function is to translate MCP requests into Dokku CLI commands, execute them over SSH, and return the results. It features a plugin-based architecture to encapsulate different areas of Dokku's functionality, such as application management, deployments, and core system operations.
Sources: README.md:3-8, README.md:32-41
Architecture
The server's architecture is founded on Domain-Driven Design (DDD) principles, promoting a clean separation of concerns between business logic and technical implementation. It also features a modular, plugin-based system for extensibility.
Sources: README.md:208-216, CONTRIBUTING.md:78-79
High-Level Overview
This diagram illustrates the main components and their interactions. An MCP Client communicates with the Dokku MCP Server, which uses its plugin system and a dedicated Dokku API client to manage a remote Dokku instance via SSH.
Architectural Layers
The codebase is structured into three distinct layers as per DDD guidelines:
- Domain Layer (
internal/domain): Contains the core business logic, entities, and repository interfaces. This layer is independent of any specific technology. - Application Layer (
internal/application): Orchestrates use cases by coordinating domain objects. - Infrastructure Layer (
internal/infrastructure): Provides concrete implementations for the domain's repository interfaces, interacting with external systems like the Dokku CLI.
Sources: README.md:208-212
Project Structure
The repository is organized to reflect its architectural principles:
dokku-mcp/
├── cmd/ # Entry points for the application
│ └── server/ # Server main command
├── internal/ # Private application code
│ ├── server/ # MCP server and adapter
│ ├── server-plugin/ # Plugin system infrastructure
│ ├── server-plugins/ # Actual plugin implementations (app, core, etc.)
│ ├── dokku-api/ # Dokku CLI client and API
│ └── shared/ # Shared domain types and services
├── pkg/ # Reusable packages (config, logger, etc.)
└── scripts/ # Helper scripts
Sources: README.md:218-228
Key Features
The server exposes a range of Dokku's capabilities through its plugin system.
| Feature | Description | Relevant Plugin(s) |
|---|---|---|
| Application Management | Create, deploy, scale, configure, and check the status of applications. | app |
| Asynchronous Deployments | Initiates deployments and returns immediately with a tracking ID, while a background poller monitors the actual status on Dokku. | deployment |
| System & Plugin Info | Provides resources to list server information, installed Dokku plugins, and their statuses. | core |
| Onboarding & Discovery | Offers dedicated resources for LLMs to discover available tools, prompts, and capabilities. | onboarding |
| Security | Implements a command blacklist and validates commands to prevent injection attacks. | dokku-api (client) |
Sources: internal/server-plugins/app/plugin.go:60-90, PHASE1_IMPLEMENTATION.md:11-23, internal/server-plugins/core/plugin.go:68-87, internal/server-plugins/onboarding/plugin.go:37-59, internal/dokku-api/client.go:21-55
Getting Started
Installation
You can install the Dokku MCP server using pre-built binaries or by building from the source.
Pre-built Binaries:
# Linux (amd64)
curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/download/v0.2.0/dokku-mcp-linux-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/
Build from Source:
git clone https://github.com/dokku-mcp/dokku-mcp.git
cd dokku-mcp
make build
Sources: README.md:109-130
Configuration
The server is configured via a config.yaml file or environment variables. Environment variables (prefixed with DOKKU_MCP_) always override file settings.
Example config.yaml for local development:
# Dokku MCP Server Configuration for Local Development
ssh:
host: "127.0.0.1"
port: 3022
user: "dokku"
key_path: ".ssh/dokku_mcp_test"
log_level: "debug"
security:
blacklist:
- "destroy"
- "uninstall"
- "remove"
Sources: scripts/setup-dokku-local.sh:84-113, README.md:132-171
Key Environment Variables:
| Variable | Description | Example |
|---|---|---|
DOKKU_MCP_SSH_HOST | The hostname or IP of the Dokku server. | your-dokku-host.com |
DOKKU_MCP_SSH_PORT | The SSH port for the Dokku server. | 22 |
DOKKU_MCP_SSH_USER | The SSH user for Dokku. | dokku |
DOKKU_MCP_SSH_KEY_PATH | Absolute path to the SSH private key. | /home/user/.ssh/id_rsa |
DOKKU_MCP_SECURITY_BLACKLIST | Comma-separated list of disabled command patterns. | destroy,uninstall,remove |
DOKKU_MCP_TRANSPORT_TYPE | Client communication mode (stdio or sse). | stdio |
Sources: README.md:46-54, README.md:158-162, README.md:195-198
Local Dokku Development
For testing, a local Dokku instance can be set up using Docker. The make setup-dokku command automates this process.
This diagram shows the local setup flow.
How it Works
The Plugin System
The server's functionality is exposed through plugins that implement the ServerPlugin interface. This interface requires methods to define the plugin's identity and provide MCP Resources, Tools, and Prompts.
This class diagram shows the ServerPlugin interface and its relationship with other providers.
The app plugin, for example, provides tools like create_app and deploy_app, and a resource at dokku://apps/list to fetch all applications.
Sources: internal/server-plugins/app/plugin.go:60-90
The Dokku API Client
At the core of the server is the Dokku API client, which is responsible for all communication with the Dokku instance.
The following sequence diagram illustrates the command execution flow from a plugin to the Dokku instance.
A key feature of the client is its JSON-first approach. When a command is executed via ExecuteWithAutoFormat, the client first attempts to run the command with a --format json flag. If successful, it parses the JSON directly. If it fails or returns invalid JSON, it falls back to parsing the plain text output. This allows for more reliable data extraction from modern Dokku versions while maintaining compatibility with older ones.
Sources: internal/dokku-api/client.go:318-376
Asynchronous Deployment Tracking
To handle long-running Dokku builds without blocking the MCP client, the server uses an asynchronous deployment tracking system. When a deployment is requested, the server initiates the process on Dokku and immediately returns a unique deployment ID. A background poller then periodically queries Dokku to update the deployment's status.
Components:
- DeploymentTracker: A thread-safe, in-memory store for the state of all active and recent deployments.
- DeploymentPoller: A background worker that polls Dokku for status updates on active deployments.
- DeploymentStatusChecker: An infrastructure component that queries Dokku's
apps:reportandps:reportto determine the actual status of an application.
Sources: PHASE1_IMPLEMENTATION.md:31-99
Deployment Flow:
Sources: PHASE1_IMPLEMENTATION.md:200-218
Deployment State Machine:
This diagram shows the lifecycle of a deployment as tracked by the system.