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:*, <datastore>: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-<os>-<arch>.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)
2. 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

2. 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
2. Clone the repository:

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

3. Install development tools:

   This command installs all the necessary Go tools for development, linting, and testing.

    make install-tools

4. Set up the development environment:

   This command sets up Git hooks to ensure code quality before commits.

    make setup-dev

5. 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 Contributing for detailed guidance on how to contribute.

License

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

Copyright [Alex Galey]

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.