Configuration

Relevant source files

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

• pkg/config/config.go
• README.md
• scripts/setup-dokku-local.sh
• internal/dokku-api/ssh_integration.go
• internal/dokku-api/client.go
• scripts/start-server.sh
• internal/dokku-api/client_blacklist_test.go

The dokku-mcp server is configured through a hierarchical system that combines default values, a YAML configuration file, and environment variables. This allows for flexibility in different deployment scenarios, from local development to production environments. The configuration covers server settings, transport modes, logging, and the crucial SSH connection details for interacting with a Dokku instance.

The configuration is loaded at startup using the viper library. This system provides a clear order of precedence, ensuring that environment-specific settings can easily override defaults or file-based configurations.

Configuration Loading

The server loads its configuration in a specific order of precedence, allowing for flexible and layered settings. The viper library is used to manage this process.

This diagram illustrates the configuration loading hierarchy.

Configuration Methods

There are two primary ways to configure the server:

1. Configuration File

A YAML file named config.yaml can be placed in one of the following locations, searched in order:

1. ./config.yaml (in the same directory as the binary)
2. ~/.dokku-mcp/config.yaml (user-specific)
3. /etc/dokku-mcp/config.yaml (system-wide)

Sources: README.md:118-123, pkg/config/config.go:129-132

Here is an example config.yaml generated for local development:

# Dokku MCP Server Configuration for Local Development
# Transport configuration
transport:
  type: "stdio"
  host: "localhost"
  port: 8080

# Server configuration
host: "localhost"
port: 8080
log_level: "debug"
log_format: "json"
timeout: "30s"

# Dokku configuration
dokku_path: "dokku"

# SSH configuration for local Dokku instance
ssh:
  host: "127.0.0.1"
  port: 3022
  user: "dokku"
  key_path: ".ssh/dokku_mcp_test"

# Security configuration
security:
  blacklist:
    - "destroy"
    - "uninstall"
    - "remove"

Sources: scripts/setup-dokku-local.sh:78-112

2. Environment Variables

All configuration settings can be set or overridden using environment variables. Each variable must be prefixed with DOKKU_MCP_. Nested keys in the YAML file are represented by underscores.

For example:

export DOKKU_MCP_SSH_HOST="your-dokku-host.com"
export DOKKU_MCP_SSH_USER="dokku"
export DOKKU_MCP_LOG_LEVEL="debug"
export DOKKU_MCP_SECURITY_BLACKLIST="destroy,uninstall,remove"

Sources: README.md:133-138, pkg/config/config.go:134, scripts/start-server.sh:10-15

Configuration Structure

The entire configuration is represented by the ServerConfig struct in Go. This struct contains nested structures for different configuration areas like SSH, Transport, and Security.

Sources: pkg/config/config.go:68-83

This class diagram shows the relationships between the main configuration structs.

Main Server Settings (ServerConfig)

These are the top-level configuration options.

Parameter	Type	Default	Description
host	string	"localhost"	The host the server listens on.
port	int	8080	The port the server listens on.
log_level	string	"info"	Logging level (debug, info, warn, error).
log_format	string	"json"	Logging format (json or text).
expose_server_logs	bool	false	Whether to expose server logs as a tool.
timeout	time.Duration	30s	Default timeout for operations like SSH commands.
dokku_path	string	"/usr/bin/dokku"	Path to the Dokku executable on the remote host.
cache_enabled	bool	true	Enables caching for Dokku command outputs.
cache_ttl	time.Duration	5m	Time-to-live for cached items.

Sources: pkg/config/config.go:68-83, 85-125

Transport Configuration (transport)

This section configures how MCP clients connect to the server.

Parameter	Type	Default	Description
type	string	"stdio"	Transport mode. Can be stdio (default) or sse (Server-Sent Events).
host	string	"localhost"	Host for SSE transport.
port	int	8080	Port for SSE transport.
cors	CORSConfig	(see below)	CORS settings for SSE transport.

Sources: pkg/config/config.go:10-14, 87-97, README.md:175-180

CORS Configuration (transport.cors)

Parameter	Type	Default	Description
enabled	bool	false	Enables the CORS middleware.
allowed_origins	[]string	[]	List of allowed origins. If empty and enabled, * is used.
allowed_methods	[]string	["GET", "POST", "OPTIONS"]	Allowed HTTP methods.
allowed_headers	[]string	["Content-Type", "Authorization"]	Allowed HTTP headers.
max_age	int	300	Access-Control-Max-Age in seconds.

Sources: pkg/config/config.go:16-23, 87-97, README.md:182-191

SSH Configuration (ssh)

This is a critical section that defines how dokku-mcp connects to the Dokku host.

Parameter	Type	Default	Description
host	string	"localhost"	The hostname or IP address of the Dokku server.
port	int	3022	The SSH port on the Dokku server.
user	string	"dokku"	The SSH user to connect as (usually dokku).
key_path	string	"dokku_mcp_test"	Path to the SSH private key. If empty, ssh-agent is used.

Sources: pkg/config/config.go:25-30, 109-113, README.md:125-128

The server configuration is used to instantiate an SSHConnectionManager, which handles all SSH command execution.

This flow diagram shows how the SSH configuration is processed.

Security Configuration (security)

This section provides security controls for the server.

Parameter	Type	Default	Description
blacklist	[]string	[]	A list of command patterns to block. Any command containing a blacklisted string will be rejected.

Sources: pkg/config/config.go:37-39, 118

The blacklist is a simple but effective security measure. For example, adding "destroy" to the list will block apps:destroy. This check is performed in the ValidateCommand function before any command is executed.

Sources: internal/dokku-api/client.go:18-23, internal/dokku-api/client_blacklist_test.go:34-40

Plugin Discovery (plugin_discovery)

Parameter	Type	Default	Description
enabled	bool	true	Enables automatic discovery of installed Dokku plugins.
sync_interval	time.Duration	1m	How often to sync the list of available plugins.

Sources: pkg/config/config.go:32-35, 115-116

Configuration Validation

On startup, after loading the configuration, the validateConfig function runs a series of checks to ensure the settings are valid. If any check fails, the server will refuse to start.

The following validations are performed:

• Server port must be between 1 and 65535.
• Timeout must be a positive duration.
• Dokku path cannot be empty.
• SSH host cannot be empty.
• SSH port must be between 1 and 65535.
• SSH user cannot be empty.
• Log level must be one of debug, info, warn, or error.
• Log format must be one of json or text.

Sources: pkg/config/config.go:181-215

Summary

The configuration system in dokku-mcp is designed for both simplicity and power. By layering defaults, a config.yaml file, and environment variables, it provides a robust way to manage server behavior. The most critical sections are ssh, which enables communication with Dokku, and security, which allows administrators to enforce safety boundaries by blacklisting potentially destructive commands. Proper validation at startup ensures a fail-fast approach, preventing the server from running with an invalid or insecure configuration.