Dokku Mcp Server

Dokku MCP 服务

面向 Dokku 的 Model Context Protocol（MCP） 服务，使用 Go 编写。

版本：请参阅 releases（dokku-mcp --version）

此服务通过标准化的 Model Context Protocol（MCP）开放 Dokku 的管理功能，让大语言模型（LLM）能够与 Dokku 实例交互并进行管理。

⚠️ 早期开发阶段：此项目尚处于早期阶段，预计会有破坏性变更，不建议用于生产环境。

立即试用——将 Dokku 实例变成可由 AI 管理的 PaaS

按照安装指南操作，或获取预构建二进制文件，只需几分钟即可开始使用 cursor、claude-code、goose 以及所有支持 mcp 的 Agent 工具。

如果本地已安装 go，也可以运行 make start。

MCP Inspector Playground

无需配置完整的 MCP 客户端，即可通过专用的 make 目标快速了解此服务：

make inspect

它会构建二进制文件（如有需要），启动 MCP Inspector CLI，并通过 stdio 模式连接到服务。Inspector 会输出一个本地 URL；在浏览器中打开，即可浏览资源、提示词和工具，或发起临时调用。在将 Dokku MCP 接入 Cursor、Claude、其他 IDE 或内部工具之前，这是验证配置的好方法。

连接 MCP 客户端

此服务可与任何兼容 MCP 的客户端配合使用。

将以下内容添加到 zed、.cursor/mcp.json、windsurf、claude_desktop_config.json 或 .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"
      }
    }
  }
}

请记得将 command 路径替换为二进制文件的绝对路径。

工具

工具按插件分组。与 Dokku 插件关联的插件（例如 Let's Encrypt）仅会在安装该插件后显示。每个工具都带有 MCP 注解（标题、只读、破坏性操作、幂等性），较新的工具会返回带有输出架构的结构化内容。

区域	工具
应用	create_app、deploy_app、rollback_app、scale_app、configure_app、get_app_status、restart_app、stop_app、start_app
部署	get_deployment_status、list_deployments
日志	get_runtime_logs、follow_runtime_logs（实时日志，以进度通知流式传输）、get_failed_deploy_logs
数据存储	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）
域名	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
访问权限	list_ssh_keys、add_ssh_key、remove_ssh_key、get_registry_report、registry_login、registry_logout
服务端	get_server_logs（通过 expose_server_logs 选择启用）

资源包括 dokku://onboarding/quickstart（从这里开始）、dokku://onboarding/capabilities、dokku://onboarding/intent-map、dokku://core/server/info 和 dokku://app/{name}/logs。app_doctor 提示词会引导用户诊断应用。

部署为异步操作：deploy_app 会在代码同步完成后立即返回 deployment_id，而 get_deployment_status 会报告构建结果以及构建日志的末尾内容。

安全

服务器会使用配置的密钥通过 SSH 运行 Dokku 命令，因此请像对待该密钥一样谨慎对待它。

• 参数安全。 Dokku 的 SSH 命令会按空格拆分参数，因此每个参数都会经过检查，确保只包含 shell 安全字符。自由格式的值（环境变量、注册表密码、SSH 公钥）会进行 base64 编码或通过 stdin 发送，绝不会插入命令行。
• 允许列表 / 黑名单。 security.allowlist 将服务器限制为匹配的命令（"apps:"、"config:*"、"logs" 等）；security.blacklist 会阻止包含某个模式的命令（destroy、uninstall 等）。两者均可通过 DOKKU_MCP_SECURITY_ALLOWLIST / DOKKU_MCP_SECURITY_BLACKLIST 设置为逗号分隔的列表。
• 输出中的机密。 工具结果中的数据存储连接 URL 和密码会被屏蔽。
• 防护措施。 destroy_service 要求重复输入服务名称；除非设置了 allow_admin，否则 add_ssh_key 会拒绝包含 admin 的名称（Dokku 允许该名称添加更多密钥）。
• 远程传输。 SSE 传输目前还没有身份验证。请仅在可信网络中公开，或将其置于经过身份验证的代理之后。

路线图

提交 issue 以重新确定提案的优先级

下一步

• Streamable HTTP 传输和身份验证：替换 SSE，添加 bearer token / OAuth 支持和按令牌设置的作用域。
• 破坏性工具的确认：使用 MCP elicitation 确认 destroy/stop/remove 操作。
• 分发：Docker 镜像、Homebrew tap，以及可在主机上运行服务器的 Dokku 插件。

想法

• 发布历史记录：保留持久化的部署日志，以便回滚时从之前的发布版本中选择。
• 更多 Dokku 插件：端口、检查、cron、存储挂载。

Dokku 集成

• 已实现：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（包括 -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。
• 缺失 / 部分实现：ports:*、checks:*、storage:*、cron:*、数据存储备份。

贡献 — 报告问题或提出功能建议

提交 issue 或阅读贡献指南。

🪿 在 issue 中向 Goose AI 寻求帮助

需要 Dokku-mcp 项目的帮助？Goose AI 可以为你提供协助！只需在 GitHub issue 或拉取请求中添加 :goose 标签，Goose AI 就会自动收到通知，协助处理开发、调试、功能实现和其他项目相关任务。

Goose AI 工作示例 另一个示例

目录

• 安装
• 配置
• 安全
• 本地 Dokku 开发
• 连接 MCP 客户端
• 开发
  • 开发环境设置
  • Makefile 命令
  • 测试
• 架构
• 项目结构
• 贡献
• 许可证

安装

预编译二进制文件

下载适用于你平台的最新版本：

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

每个版本还会发布压缩归档文件（dokku-mcp-<os>-<arch>.tar.gz）。

MCP Bundle

每个稳定版本还会附带 dokku-mcp.mcpb，这是一个适用于 macOS 和 Linux 的 MCP Bundle。Claude Desktop 等 MCP 客户端可一步完成安装，并会询问 Dokku 主机、SSH 用户、端口和密钥。同一 Bundle 也会作为 io.github.dokku-MCP/dokku-mcp 发布到官方 MCP Registry。

验证安装

dokku-mcp --version

从源代码构建

如果你更愿意从源代码构建：

1. 前提条件：

   • Go（版本 1.26 或更高）

2. 克隆并构建：

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

配置

可以通过两种方式配置服务：使用 config.yaml 文件或环境变量。

配置文件

在以下任一位置创建配置文件：

• 系统范围：/etc/dokku-mcp/config.yaml
• 用户专用：~/.dokku-mcp/config.yaml
• 本地：与二进制文件位于同一目录下的 config.yaml。

以下是一个最精简的 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"

完整的可用选项列表，请参阅 config.yaml.example 文件。

环境变量

所有配置设置都可以通过以 DOKKU_MCP_ 为前缀的环境变量覆盖。嵌套键使用下划线（ssh.host → DOKKU_MCP_SSH_HOST），列表项以逗号分隔。例如：

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"

运行服务

配置完成后，即可运行服务：

dokku-mcp

服务将启动并准备好接受来自 MCP 客户端的连接。

本地 Dokku 开发

如需在无需远程 Dokku 实例的情况下进行开发和测试，可以使用 Docker 运行本地 Dokku 服务。

前提条件：

• Docker 和 Docker Compose
• Make

1. 设置本地 Dokku 容器：

   此命令将下载所需的 Docker 镜像并配置本地 Dokku 实例。只需运行一次。

   make setup-dokku
   
   make dokku-start
   

2. 停止本地 Dokku 容器：

   make dokku-stop
   

本地 Dokku 容器运行时，MCP 服务（使用默认配置）应该能够连接到它。你可以针对这个本地实例运行集成测试。

传输模式

服务支持两种客户端传输模式：

• stdio（默认）： 用于进程间直接通信的标准输入/输出。
• sse（Server-Sent Events）： 面向 Web 客户端的基于 HTTP 的传输方式。

  DOKKU_MCP_TRANSPORT_TYPE=sse dokku-mcp
  

CORS 配置

对于 SSE 传输，默认通过 Access-Control-Allow-Origin: * 处理 CORS。对于远程部署，可以启用自定义 CORS 中间件：

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

有关详细配置选项和安全最佳实践，请参阅 docs/CORS.md。

开发

本节适用于希望为项目做贡献或修改源代码的开发者。

开发环境设置

1. 前提条件：

   • Go（版本 1.26 或更高）
   • Docker 和 Docker Compose
   • Make

2. 克隆代码仓库：

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

3. 安装开发工具：

   此命令将安装开发、代码检查和测试所需的所有 Go 工具。

   make install-tools
   

4. 设置开发环境：

   此命令会设置 Git 钩子，确保提交前的代码质量。

   make setup-dev
   

5. 从源代码构建并运行：

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

Makefile 命令

项目使用 Makefile 自动执行常见任务。

• make help：显示所有可用命令。
• make check：运行所有代码质量检查（代码检查、格式化、复杂度）。
• make build：构建服务二进制文件。
• make clean：清理构建产物。

测试

• 运行所有测试：

  make test
  

  这会运行所有单元测试和集成测试，并在 coverage.html 生成 HTML 覆盖率报告。

• 针对本地 Dokku 运行集成测试： 确保本地 Dokku 容器正在运行（make dokku-start）。

  make test-integration-local
  

架构

该服务遵循**领域驱动设计（DDD）**原则，并清晰划分以下层次：

• 领域层（internal/domain）： 核心业务逻辑、实体和仓库接口。
• 应用层（internal/application）： 用例编排与协调。
• 基础设施层（internal/infrastructure）： 接口的实现，例如 Dokku 客户端、数据库和外部服务。

该项目采用位于 internal/server-plugins 的基于插件的架构，每个插件封装一组特定的 Dokku 功能（例如 app、core、deployment）。

更多详情请参阅 docs/ 目录中的文档。

项目结构

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

贡献

欢迎贡献！有关如何贡献的详细指南，请参阅贡献指南。

许可证

本项目采用 Apache License 2.0 许可协议，详情请参阅 LICENSE 文件。

版权所有 [Alex Galey]

根据 Apache License（版本 2.0，“许可证”）授权； 除遵守许可证外，您不得使用此文件。 您可以在以下网址获取许可证副本：

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

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”提供， 不附带任何明示或暗示的保证或条件。 有关许可证下权限和限制的具体规定，请参阅许可证。