Dokku MCP Server

Dokku MCP Server

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

Version: see releases (dokku-mcp --version)

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.

Try it now — turn your Dokku instance into an AI-manageable PaaS

Follow Installation or grab a prebuilt binary to get started in minutes with cursor, claude-code, goose and all agentic tools which support mcp.

Or make start if you already have go locally.

MCP Inspector Playground

For a quick tour of the server without wiring up a full MCP client, use the dedicated make target:

make inspect

It builds the binary (if needed), launches the MCP Inspector CLI, and connects it to the server in stdio mode. Inspector prints a local URL—open it in your browser to browse resources, prompts, and tools, or to issue ad-hoc calls. This is a great way to validate your setup before wiring Dokku MCP into Cursor, Claude, other IDE or internal tools.

Connecting MCP Clients

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

Add the following to your zed, .cursor/mcp.json, windsurf, claude_desktop_config.json or .mcp.json:

{

"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 the binary.*

Tools

Tools are grouped by plugin. Plugins tied to a Dokku plugin (for example Let's Encrypt) only appear when that plugin is installed. Every tool carries MCP annotations (title, read-only, destructive, idempotent), and newer tools return structured content with an output schema.

Resources include dokku://onboarding/quickstart (start here), dokku://onboarding/capabilities, dokku://onboarding/intent-map, dokku://core/server/info and dokku://app/{name}/logs. The app_doctor prompt walks through diagnosing an application.

Deployments are asynchronous: deploy_app returns a deployment_id as soon as the code is synced, and get_deployment_status reports the build outcome and the tail of the build log.

Security

The server runs Dokku commands over SSH with the configured key, so treat it like that key.

• Argument safety. Dokku's SSH command word-splits arguments, so every argument is checked against a shell-safe character set. Free-form values (environment variables, registry passwords, SSH public keys) are sent base64-encoded or over stdin, never interpolated into the command line.
• Allowlist / blacklist. security.allowlist restricts the server to matching commands ("apps:", "config:*", "logs", ...); security.blacklist blocks commands containing a pattern (destroy, uninstall, ...). Both can be set with DOKKU_MCP_SECURITY_ALLOWLIST / DOKKU_MCP_SECURITY_BLACKLIST as comma-separated lists.
• Secrets in output. Datastore connection URLs and passwords are masked in tool results.
• Guard rails. destroy_service requires the service name to be repeated; add_ssh_key refuses names containing admin (which Dokku lets add further keys) unless allow_admin is set.
• Remote transport. The SSE transport has no authentication yet. Only expose it on a trusted network or behind an authenticating proxy.

Roadmap

Submit an issue for re-priorizing proposal

NEXT

• Streamable HTTP transport and authentication: replace SSE, add bearer token / OAuth support and per-token scopes.
• Confirmation for destructive tools: use MCP elicitation for destroy/stop/remove operations.
• Distribution: Docker image, Homebrew tap and a Dokku plugin that runs the server on the host.

IDEAS

• Release history: keep a durable deployment log so rollbacks can pick from previous releases.
• More Dokku plugins: ports, checks, cron, storage mounts.

Dokku integrations

• Implemented: apps:list, apps:info, apps:create, apps:exists, apps:report, config:show, config:set --encoded, ps:scale, ps:report, ps:rebuild, ps:restart, ps:stop, ps:start, git:sync, logs (including -t follow), logs:failed, domains:report, domains:add, domains:remove, domains:add-global, letsencrypt:*, :create/info/list/link/unlink/links/logs/destroy, ssh-keys:list/add/remove, registry:login/logout/report, plugin:list, version, proxy:report, scheduler:report, git:report.
• Missing/partial: ports:*, checks:*, storage:*, cron:*, datastore backups.

Contribute — report issues or propose features

Open an issue or read Contributing.

🪿 Get Help from Goose AI within issues

Need help with the dokku-mcp project? Goose AI is available to assist you! Simply tag your GitHub issues or pull requests with the :goose label, and Goose AI will automatically be notified to help with development, debugging, feature implementation, and other project-related tasks.

Example of Goose AI in action Another example

Table of Contents

• Installation
• Configuration
• Security
• Local Dokku Development
• Connecting MCP Clients
• Development
• Development Setup
• Makefile Commands
• Testing
• Architecture
• Project Structure
• Contributing
• License

Installation

Pre-built Binaries

Download the latest release for your platform:

# Linux (amd64; also available: arm64, arm)

curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/latest/download/dokku-mcp-linux-amd64 chmod +x dokku-mcp sudo mv dokku-mcp /usr/local/bin/

macOS (amd64; also available: arm64)

curl -L -o dokku-mcp https://github.com/dokku-mcp/dokku-mcp/releases/latest/download/dokku-mcp-darwin-amd64 chmod +x dokku-mcp sudo mv dokku-mcp /usr/local/bin/

Compressed archives (dokku-mcp- - .tar.gz) are also published with each release.

MCP Bundle

Each stable release also ships dokku-mcp.mcpb, an MCP Bundle for macOS and Linux that MCP clients such as Claude Desktop install in one step, asking for the Dokku host, SSH user, port and key. The same bundle is published to the official MCP Registry as io.github.dokku-MCP/dokku-mcp.

Verify Installation

dokku-mcp --version

Build from Source

If you prefer to build from source:

1. Prerequisites:

• Go (version 1.26 or later)

1. Clone and build:

   git clone https://github.com/dokku-mcp/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 config.yaml.example file.

Environment Variables

All configuration settings can be overridden with environment variables prefixed with DOKKU_MCP_. Nested keys use underscores (ssh.host → DOKKU_MCP_SSH_HOST) and lists are comma-separated. 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_ALLOWLIST="apps:,config:,ps:,git:sync,logs,version"

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

1. 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

make dokku-start

1. 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.

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

CORS Configuration

For SSE transport, CORS is handled by default with Access-Control-Allow-Origin: *. For remote deployments, you can enable custom CORS middleware:

transport:

type: sse cors: enabled: true allowed_origins:

• "https://app.example.com"
• "*.example.com"

See docs/CORS.md for detailed configuration options and security best practices.

Development

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

Development Setup

1. Prerequisites:

• Go (version 1.26 or later)
• Docker and Docker Compose
• Make

1. Clone the repository:

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

cd dokku-mcp

1. Install development tools:

This command inst