Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/start-server.sh
• CONTRIBUTING.md
• scripts/setup-dokku-local.sh
• scripts/setup-dev.sh
• internal/server-plugins/app/plugin.go
• internal/dokku-api/client.go
• internal/server-plugins/onboarding/plugin.go
• PHASE1_IMPLEMENTATION.md

The Dokku MCP Server is a Go application that exposes Dokku's management capabilities through the Model Context Protocol (MCP). This allows Large Language Models (LLMs) and other agentic tools to interact with and manage a Dokku instance. This guide covers how to install, configure, and run the server, as well as how to set up a local development environment for contributing to the project.

The server features a plugin-based architecture, with each plugin encapsulating a specific set of Dokku features. Core plugins include apps for application management, core for server info, and onboarding for discovery resources.

Sources: README.md:5-11, README.md:281-286

Installation

You can get started by either downloading a pre-built binary or by building the server from the source code.

Pre-built Binaries

The quickest way to install dokku-mcp is to download a pre-built binary for your operating system.

# 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/

# macOS (amd64)  
curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/download/v0.2.0/dokku-mcp-darwin-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/

After installation, you can verify it by checking the version:

dokku-mcp --version

Sources: README.md:120-136

Build from Source

To build from source, you need Go version 1.25 or later installed.

1. Clone the repository:

   git clone https://github.com/dokku-mcp/dokku-mcp.git
   cd dokku-mcp
   

2. Build the binary:

   make build
   

This will create the executable at ./build/dokku-mcp.

Sources: README.md:138-150

The installation process can be visualized as follows:

This diagram shows the two paths to installing the dokku-mcp server.
Sources: README.md:120-150

Configuration

The server can be configured using a YAML file or environment variables. Environment variables will always override settings from a configuration file.

Configuration File

The server looks for a config.yaml file in the following locations, in order of precedence:

1. Local: config.yaml (in the same directory as the binary)
2. User-specific: ~/.dokku-mcp/config.yaml
3. System-wide: /etc/dokku-mcp/config.yaml

A minimal config.yaml for connecting to a remote Dokku host looks like this:

ssh:
  host: "your-dokku-host.com"
  user: "dokku"
  # key_path: "/path/to/your/ssh/private/key" # Optional, uses ssh-agent if empty

log_level: "info"

The scripts/setup-dokku-local.sh script can generate a more detailed config.yaml for local development.

Sources: README.md:152-169, scripts/setup-dokku-local.sh:86-121

Environment Variables

All configuration options can be set using environment variables prefixed with DOKKU_MCP_.

Variable	Description	Default
DOKKU_MCP_SSH_HOST	The hostname or IP of the Dokku server.	127.0.0.1
DOKKU_MCP_SSH_PORT	The SSH port of the Dokku server.	22
DOKKU_MCP_SSH_USER	The SSH user for the Dokku server.	dokku
DOKKU_MCP_SSH_KEY_PATH	Absolute path to the SSH private key.	(uses ssh-agent)
DOKKU_MCP_LOG_LEVEL	Logging level (e.g., debug, info).	info
DOKKU_MCP_SECURITY_BLACKLIST	Comma-separated list of disabled commands.	destroy,uninstall,remove
DOKKU_MCP_TRANSPORT_TYPE	Client communication mode (stdio or sse).	stdio

Sources: README.md:58-65, README.md:171-177, scripts/start-server.sh:11-16

The configuration loading process gives priority to environment variables.

This diagram illustrates the configuration override logic.
Sources: README.md:152-177

Running the Server

Once configured, you can run the server directly or using the provided Makefile target.

To run the compiled binary:

dokku-mcp

If you are in the source directory, you can use make:

# This command builds the binary (if needed) and starts the server.
make start

The scripts/start-server.sh script handles building the server, creating a default config if one doesn't exist, and exporting environment variables before execution.

Sources: README.md:179-182, README.md:232-235, scripts/start-server.sh:60-63, 134-137

Transport Modes

The server supports two transport modes for client communication:

• stdio (default): For direct process communication, typically used by local clients like IDE extensions.
• sse (Server-Sent Events): An HTTP-based transport for web clients.

You can select the mode via an environment variable:

DOKKU_MCP_TRANSPORT_TYPE=sse dokku-mcp

Sources: README.md:200-206

Connecting an MCP Client

To connect an MCP-compatible client (like Cursor, Zed, or Claude Desktop), you need to add a server configuration to its JSON file (e.g., .cursor/mcp.json). This configuration tells the client how to launch and communicate with the dokku-mcp server.

{
  "mcpServers": {
    "dokku": {
      "command": "/home/user/dokku-mcp/build/dokku-mcp",
      "args": [],
      "env": {
        "DOKKU_MCP_SECURITY_BLACKLIST": "destroy,uninstall,remove",
        "DOKKU_MCP_SSH_HOST": "127.0.0.1",
        "DOKKU_MCP_SSH_KEY_PATH": "/home/user/.ssh/id_rsa",
        "DOKKU_MCP_SSH_PORT": "22",
        "DOKKU_MCP_SSH_USER": "dokku"
      }
    }
  }
}

Remember to replace the command path with the absolute path to your dokku-mcp binary.

The following sequence diagram shows the interaction when a client connects.

This diagram shows the startup and a sample tool call flow between the MCP client, the dokku-mcp server, and the Dokku host.
Sources: README.md:54-70, internal/dokku-api/client.go:21-49

Local Development

For those who want to contribute to the project, a comprehensive local development setup is available.

Local Dokku Instance

You can run a local Dokku server in Docker for testing, which avoids the need for a remote Dokku instance.
Prerequisites: Docker, Docker Compose, and Make.

1. Set up the local Dokku container: This command downloads Docker images, configures the Dokku instance, generates an SSH key, and creates a config.yaml file pointing to the local container. It only needs to be run once.

   make setup-dokku
   

2. Start the local Dokku container:

   make dokku-start
   

3. Stop the container:

   make dokku-stop
   

Sources: README.md:184-198, scripts/setup-dokku-local.sh

Development Environment Setup

The development workflow is streamlined with make and Git hooks.

The setup flow is as follows:

This diagram outlines the one-time setup and the recurring development loop.
Sources: CONTRIBUTING.md:28-34, scripts/setup-dev.sh

1. Clone the repository:

   git clone https://github.com/dokku-mcp/dokku-mcp.git
   cd dokku-mcp
   

2. Install development tools: This installs Go tools for linting, formatting, and testing.

   make install-tools
   

3. Set up Git hooks: This configures a pre-commit hook to automatically format code and run checks, ensuring code quality.

   make setup-dev
   

Sources: CONTRIBUTING.md:28-34, scripts/setup-dev.sh:5-9

Makefile Commands

The Makefile provides several useful commands for development:

Command	Description
make help	Show all available commands.
make build	Build the server binary.
make start	Build and run the server from source.
make check	Run all code quality checks (linting, formatting, etc.).
make test	Run all unit and integration tests and generate a coverage report.
make test-integration-local	Run integration tests against the local Dokku container.
make clean	Clean up build artifacts.

Sources: README.md:237-253

By following this guide, you should be able to successfully install, configure, and run the Dokku MCP server. For developers, the local setup provides a complete environment for testing and contributing to the project.