dokku-mcp by alex-galey - MCP Server

Dokku MCP Server

Model Context Protocol (MCP) server for Dokku, written in Go.

Version: v0.1.1-alpha

This server exposes Dokku's management capabilities through the standardized Model Context Protocol (MCP), allowing Large Language Models (LLMs) to interact with and manage a Dokku instance.

⚠️ Early Development: This project is in its early stages. Breaking changes are expected, and it is not recommended for production use.

Installation
Configuration
Local Dokku Development
Connecting MCP Clients
Development
Architecture
Project Structure
Contributing
License

Installation

Pre-built Binaries

Download the latest release for your platform:

# Linux (amd64 / arm64 / arm)
curl -L -o dokku-mcp https://github.com/alex-galey/dokku-mcp/releases/download/v0.1.1-alpha/dokku-mcp-linux-amd64
chmod +x dokku-mcp
sudo mv dokku-mcp /usr/local/bin/

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

Verify Installation

dokku-mcp --version

Build from Source

If you prefer to build from source:

Prerequisites:
- Go (version 1.24 or later)

Clone and build:

git clone https://github.com/alex-galey/dokku-mcp.git
cd dokku-mcp
make build

Configuration

The server can be configured in two ways: using a config.yaml file or via environment variables.

Configuration File

Create a configuration file at one of the following locations:

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

Here is a minimal config.yaml example:

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"

For a full list of available options, please refer to the file.

Environment Variables

All configuration settings can be overridden with environment variables prefixed with DOKKU_MCP_. For example:

export DOKKU_MCP_SSH_HOST="your-dokku-host.com"
export DOKKU_MCP_SSH_USER="dokku"
export DOKKU_MCP_LOG_LEVEL="debug"

Running the Server

Once configured, you can run the server:

dokku-mcp

The server will start and be ready to accept connections from an MCP client.

Local Dokku Development

For development and testing without needing a remote Dokku instance, you can run a local Dokku server using Docker.

Prerequisites:

Docker and Docker Compose
Make

Set up the local Dokku container:

This command will download the necessary Docker images and configure the local Dokku instance. It only needs to be run once.
```
make setup-dokku
```
Start the local Dokku container:
```
make dokku-start
```
Stop the local Dokku container:
```
make dokku-stop
```

When the local Dokku container is running, the MCP server (with default config) should be able to connect to it. You can run integration tests against this local instance.

Connecting MCP Clients

The server can be used with any MCP-compatible client.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "dokku": {
      "command": "/path/to/your/dokku-mcp",
      "args": [],
      "env": {
        "DOKKU_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Remember to replace the command path with the absolute path to the binary.

Transport Modes

The server supports two transport modes for clients:

stdio (default): Standard input/output for direct process communication.
sse (Server-Sent Events): HTTP-based transport for web clients.
```
DOKKU_MCP_TRANSPORT_TYPE=sse dokku-mcp
```

Development

This section is for developers who want to contribute to the project or modify the source code.

Development Setup

Prerequisites:
- Go (version 1.24 or later)
- Docker and Docker Compose
- Make

Clone the repository:

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

Install development tools:

This command installs all the necessary Go tools for development, linting, and testing.
```
make install-tools
```
Set up the development environment:

This command sets up Git hooks to ensure code quality before commits.
```
make setup-dev
```

Build and run from source:

# This command builds the binary and starts the server.
make start

Makefile Commands

The project uses a Makefile to automate common tasks.

make help: Show all available commands.
make check: Run all code quality checks (linting, formatting, complexity).
make build: Build the server binary.
make clean: Clean up build artifacts.

Testing

Run all tests:
```
make test
```
This runs all unit and integration tests and generates an HTML coverage report at coverage.html.
Run integration tests against local Dokku: Make sure your local Dokku container is running (make dokku-start).
```
make test-integration-local
```

Architecture

The server follows Domain-Driven Design (DDD) principles, with a clear separation between:

Domain Layer (internal/domain): Core business logic, entities, and repository interfaces.
Application Layer (internal/application): Use case orchestration and coordination.
Infrastructure Layer (internal/infrastructure): Implementations of interfaces, such as the Dokku client, databases, and external services.

It features a plugin-based architecture located in internal/server-plugins, where each plugin encapsulates a specific set of Dokku features (e.g., app, core, deployment).

For more details, please refer to the documentation in the docs/ directory.

Project Structure

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.)
├── docs/                   # Project documentation
└── scripts/                # Helper scripts

Contributing

Contributions are welcome! Please see for detailed guidance on how to contribute.

License

This project is under the Apache License 2.0 - see the file for details.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.