Dokku

Um servidor MCP para gerenciar aplicações no Dokku, o PaaS de código aberto.

Documentação

Servidor MCP Dokku

Servidor Model Context Protocol (MCP) para Dokku, escrito em Go.

Versão: veja releases (dokku-mcp --version)

Este servidor expõe as capacidades de gerenciamento do Dokku por meio do Model Context Protocol (MCP) padronizado, permitindo que Grandes Modelos de Linguagem (LLMs) interajam e gerenciem uma instância Dokku.

⚠️ Desenvolvimento inicial: Este projeto está em estágio inicial. Mudanças significativas são esperadas e não é recomendado para uso em produção.

Experimente agora — transforme sua instância Dokku em uma PaaS gerenciável por IA

Siga a Instalação ou baixe um binário pré-compilado para começar em minutos com cursor, claude-code, goose e todas as ferramentas de agente que suportam mcp.

Ou make start se você já tiver go instalado localmente.

Playground do MCP Inspector

Para um tour rápido do servidor sem configurar um cliente MCP completo, use o alvo make dedicado:

make inspect

Ele compila o binário (se necessário), inicia o CLI do MCP Inspector e o conecta ao servidor no modo stdio. O Inspector imprime uma URL local — abra-a no seu navegador para navegar por recursos, prompts e ferramentas, ou para fazer chamadas ad-hoc. Esta é uma ótima maneira de validar sua configuração antes de conectar o Dokku MCP ao Cursor, Claude, outras IDEs ou ferramentas internas.

Conectando Clientes MCP

O servidor pode ser usado com qualquer cliente compatível com MCP.

Adicione o seguinte ao seu zed, .cursor/mcp.json, windsurf, claude_desktop_config.json ou .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"
      }
    }
  }
}

Lembre-se de substituir o caminho command pelo caminho absoluto do binário.

Ferramentas

As ferramentas são agrupadas por plugin. Plugins vinculados a um plugin Dokku (por exemplo, Let's Encrypt) só aparecem quando esse plugin está instalado. Cada ferramenta carrega anotações MCP (título, somente leitura, destrutiva, idempotente), e ferramentas mais recentes retornam conteúdo estruturado com um esquema de saída.

Área	Ferramentas
Aplicações	`create_app`, `deploy_app`, `rollback_app`, `scale_app`, `configure_app`, `get_app_status`, `restart_app`, `stop_app`, `start_app`
Implantações	`get_deployment_status`, `list_deployments`
Logs	`get_runtime_logs`, `follow_runtime_logs` (ao vivo, transmitidos como notificações de progresso), `get_failed_deploy_logs`
Bancos de dados	`list_services`, `create_service`, `get_service_info`, `link_service`, `unlink_service`, `get_service_logs`, `destroy_service` (postgres, mysql, mariadb, redis, mongo, rabbitmq, memcached, clickhouse, elasticsearch)
Domínios	`get_app_domains`, `add_app_domain`, `remove_app_domain`, `list_global_domains`, `add_global_domain`
HTTPS	`get_letsencrypt_status`, `enable_letsencrypt`, `disable_letsencrypt`, `set_letsencrypt_email`
Acesso	`list_ssh_keys`, `add_ssh_key`, `remove_ssh_key`, `get_registry_report`, `registry_login`, `registry_logout`
Servidor	`get_server_logs` (opt-in com `expose_server_logs`)

Os recursos incluem dokku://onboarding/quickstart (comece aqui), dokku://onboarding/capabilities, dokku://onboarding/intent-map, dokku://core/server/info e dokku://app/{name}/logs. O prompt app_doctor orienta no diagnóstico de uma aplicação.

As implantações são assíncronas: deploy_app retorna um deployment_id assim que o código é sincronizado, e get_deployment_status relata o resultado da compilação e o final do log de compilação.

Segurança

O servidor executa comandos Dokku via SSH com a chave configurada, portanto, trate-o como essa chave.

Segurança de argumentos. O comando SSH do Dokku divide argumentos por espaços, então cada argumento é verificado contra um conjunto de caracteres seguro para shell. Valores de formato livre (variáveis de ambiente, senhas de registro, chaves públicas SSH) são enviados codificados em base64 ou via stdin, nunca interpolados na linha de comando.
Lista de permissões / bloqueios. security.allowlist restringe o servidor a comandos correspondentes ("apps:", "config:*", "logs", ...); security.blacklist bloqueia comandos que contenham um padrão (destroy, uninstall, ...). Ambos podem ser definidos com DOKKU_MCP_SECURITY_ALLOWLIST / DOKKU_MCP_SECURITY_BLACKLIST como listas separadas por vírgulas.
Segredos na saída. URLs de conexão de banco de dados e senhas são mascaradas nos resultados das ferramentas.
Proteções. destroy_service exige que o nome do serviço seja repetido; add_ssh_key recusa nomes contendo admin (que o Dokku permite adicionar mais chaves) a menos que allow_admin esteja definido.
Transporte remoto. O transporte SSE não tem autenticação ainda. Exponha-o apenas em uma rede confiável ou atrás de um proxy autenticador.

Roadmap

Envie uma issue para propor re-priorização

Transporte HTTP transmissível e autenticação: substituir SSE, adicionar suporte a bearer token / OAuth e escopos por token.
Confirmação para ferramentas destrutivas: usar elicitação MCP para operações de destroy/stop/remove.
Distribuição: imagem Docker, Homebrew tap e um plugin Dokku que execute o servidor no host.

IDEIAS

Histórico de versões: manter um log de implantação durável para que rollbacks possam escolher entre versões anteriores.
Mais plugins Dokku: portas, verificações, cron, montagens de armazenamento.

Integrações Dokku

Implementado: 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 (incluindo acompanhamento -t), 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.
Ausente/parcial: ports:*, checks:*, storage:*, cron:*, backups de banco de dados.

Contribua — relate problemas ou proponha recursos

Abra uma issue ou leia Contribuindo.

🪿 Obtenha ajuda da Goose AI nas issues

Precisa de ajuda com o projeto dokku-mcp? A Goose AI está disponível para ajudar! Basta marcar suas issues ou pull requests do GitHub com o rótulo :goose, e a Goose AI será notificada automaticamente para ajudar com desenvolvimento, depuração, implementação de recursos e outras tarefas relacionadas ao projeto.

Exemplo da Goose AI em ação Outro exemplo

Instalação

Binários Pré-compilados

Baixe a versão mais recente para sua plataforma:

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

Arquivos compactados (dokku-mcp-<os>-<arch>.tar.gz) também são publicados com cada versão.

Pacote MCP

Cada versão estável também inclui dokku-mcp.mcpb, um Pacote MCP para macOS e Linux que clientes MCP como o Claude Desktop instalam em uma única etapa, solicitando o host Dokku, usuário SSH, porta e chave. O mesmo pacote é publicado no Registro MCP oficial como io.github.dokku-MCP/dokku-mcp.

Verificar Instalação

dokku-mcp --version

Compilar a partir do Código Fonte

Se preferir compilar a partir do código fonte:

Pré-requisitos:
- Go (versão 1.26 ou posterior)

Clonar e compilar:

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

Configuração

O servidor pode ser configurado de duas maneiras: usando um arquivo config.yaml ou via variáveis de ambiente.

Arquivo de Configuração

Crie um arquivo de configuração em um dos seguintes locais:

Sistema: /etc/dokku-mcp/config.yaml
Específico do usuário: ~/.dokku-mcp/config.yaml
Local: config.yaml no mesmo diretório do binário.

Aqui está um exemplo mínimo de config.yaml:

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"

Para uma lista completa de opções disponíveis, consulte o arquivo config.yaml.example.

Variáveis de Ambiente

Todas as configurações podem ser substituídas com variáveis de ambiente prefixadas com DOKKU_MCP_. Chaves aninhadas usam sublinhados (ssh.host → DOKKU_MCP_SSH_HOST) e listas são separadas por vírgulas. Por exemplo:

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"

Executando o Servidor

Uma vez configurado, você pode executar o servidor:

dokku-mcp

O servidor iniciará e estará pronto para aceitar conexões de um cliente MCP.

Desenvolvimento Local do Dokku

Para desenvolvimento e testes sem precisar de uma instância Dokku remota, você pode executar um servidor Dokku local usando Docker.

Pré-requisitos:

Docker e Docker Compose
Make

Configurar o contêiner Dokku local:

Este comando baixará as imagens Docker necessárias e configurará a instância Dokku local. Só precisa ser executado uma vez.
```
make setup-dokku

make dokku-start
```
Parar o contêiner Dokku local:
```
make dokku-stop
```

Quando o contêiner Dokku local estiver em execução, o servidor MCP (com configuração padrão) deve conseguir se conectar a ele. Você pode executar testes de integração contra esta instância local.

Modos de Transporte

O servidor suporta dois modos de transporte para clientes:

stdio (padrão): Entrada/saída padrão para comunicação direta de processos.
sse (Server-Sent Events): Transporte baseado em HTTP para clientes web.
```
DOKKU_MCP_TRANSPORT_TYPE=sse dokku-mcp
```

Configuração CORS

Para transporte SSE, o CORS é tratado por padrão com Access-Control-Allow-Origin: *. Para implantações remotas, você pode habilitar middleware CORS personalizado:

transport:
  type: sse
  cors:
    enabled: true
    allowed_origins:
      - "https://app.example.com"
      - "*.example.com"

Consulte docs/CORS.md para opções de configuração detalhadas e melhores práticas de segurança.

Desenvolvimento

Esta seção é para desenvolvedores que desejam contribuir com o projeto ou modificar o código fonte.

Configuração de Desenvolvimento

Pré-requisitos:
- Go (versão 1.26 ou posterior)
- Docker e Docker Compose
- Make

Clonar o repositório:

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

Instalar ferramentas de desenvolvimento:

Este comando instala todas as ferramentas Go necessárias para desenvolvimento, linting e testes.
```
make install-tools
```
Configurar o ambiente de desenvolvimento:

Este comando configura hooks do Git para garantir qualidade de código antes de commits.
```
make setup-dev
```

Compilar e executar a partir do código fonte:

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

Comandos do Makefile

O projeto usa um Makefile para automatizar tarefas comuns.

make help: Mostrar todos os comandos disponíveis.
make check: Executar todas as verificações de qualidade de código (linting, formatação, complexidade).
make build: Compilar o binário do servidor.
make clean: Limpar artefatos de compilação.

Testes

Executar todos os testes:
```
make test
```
Isso executa todos os testes unitários e de integração e gera um relatório de cobertura HTML em coverage.html.
Executar testes de integração contra o Dokku local: Certifique-se de que seu contêiner Dokku local esteja em execução (make dokku-start).
```
make test-integration-local
```

Arquitetura

O servidor segue princípios de Domain-Driven Design (DDD), com uma separação clara entre:

Camada de Domínio (internal/domain): Lógica de negócios central, entidades e interfaces de repositório.
Camada de Aplicação (internal/application): Orquestração e coordenação de casos de uso.
Camada de Infraestrutura (internal/infrastructure): Implementações de interfaces, como o cliente Dokku, bancos de dados e serviços externos.

Possui uma arquitetura baseada em plugins localizada em internal/server-plugins, onde cada plugin encapsula um conjunto específico de recursos Dokku (por exemplo, app, core, deployment).

Para mais detalhes, consulte a documentação no diretório docs/.

Estrutura do Projeto

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

Contribuindo

Contribuições são bem-vindas! Consulte Contribuindo para orientações detalhadas sobre como contribuir.

Licença

Este projeto está sob a Licença Apache 2.0 — consulte o arquivo LICENSE para detalhes. Copyright [Alex Galey]

Licenciado sob a Licença Apache, Versão 2.0 (a "Licença"); você não pode usar este arquivo exceto em conformidade com a Licença. Você pode obter uma cópia da Licença em

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

A menos que exigido por lei aplicável ou acordado por escrito, o software distribuído sob a Licença é distribuído "COMO ESTÁ", SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas. Consulte a Licença para obter as permissões específicas e limitações sob a Licença.