Dokploy MCP Server

Dokploy MCP 服务

⚠️ 项目已停止维护

此项目已迁移至 Dokploy 官方组织，此仓库将不再维护。

📍 新的官方仓库： https://github.com/Dokploy/mcp

请迁移至官方仓库，以获取最新更新和持续支持。

Dokploy MCP 服务将 Dokploy 功能作为工具提供，可通过模型上下文协议（MCP）调用。它允许兼容 MCP 的客户端（例如 AI 模型和其他应用程序）以编程方式与您的 Dokploy 服务交互。

🚨 此项目已不再维护。请立即迁移至官方仓库。

📖 迁移指南 → | 🔗 官方仓库 →

此服务专注于用于直接执行 Dokploy API 操作的工具，提供简洁高效的项目和应用管理接口。

🛠️ 入门

要求

• Node.js >= v18.0.0（或 Docker）
• Cursor、VS Code、Claude Desktop 或其他 MCP 客户端
• 正在运行的 Dokploy 服务实例

在 Cursor 中安装

前往：Settings -> Cursor Settings -> MCP -> Add new global MCP server

将以下内容添加到 Cursor 的 ~/.cursor/mcp.json 文件中。您也可以在项目文件夹中创建 .cursor/mcp.json，以便在特定项目中安装。更多信息请参阅 Cursor MCP 文档。

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "bunx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-net", "npm:@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

在 Windsurf 中安装

将以下内容添加到 Windsurf MCP 配置文件中。更多信息请参阅 Windsurf MCP 文档。

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

在 VS Code 中安装

将以下内容添加到 VS Code MCP 配置文件中。更多信息请参阅 VS Code MCP 文档。

{
  "servers": {
    "dokploy-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

在 Zed 中安装

将以下内容添加到 Zed 的 settings.json 中。更多信息请参阅 Zed Context Server 文档。

{
  "context_servers": {
    "dokploy-mcp": {
      "command": {
        "path": "npx",
        "args": ["-y", "@ahdev/dokploy-mcp"]
      },
      "settings": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

在 Claude Desktop 中安装

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 文件中。更多信息请参阅 Claude Desktop MCP 文档。

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

在 BoltAI 中安装

打开应用的“Settings”页面，前往“Plugins”，然后输入以下 JSON：

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

使用 Docker

Docker 容器支持 stdio 和 HTTP 两种传输模式，可灵活适应不同的部署场景。

1. 构建 Docker 镜像：

   git clone https://github.com/andradehenrique/dokploy-mcp.git
   cd dokploy-mcp
   docker build -t dokploy-mcp .
   

2. 手动运行 Docker 命令：

   stdio 模式（适用于 MCP 客户端）：

   docker run -it --rm \
     -e DOKPLOY_URL=https://your-dokploy-server.com/api \
     -e DOKPLOY_API_KEY=your_token_here \
     dokploy-mcp
   

   HTTP 模式（适用于 Web 应用）：

   docker run -it --rm \
     -p 3000:3000 \
     -e MCP_TRANSPORT=http \
     -e DOKPLOY_URL=https://your-dokploy-server.com/api \
     -e DOKPLOY_API_KEY=your_token_here \
     dokploy-mcp
   

3. Docker Compose：

   在生产环境部署时，请使用提供的 docker-compose.yml：

   # 启动 HTTP 服务
   docker-compose up -d dokploy-mcp-http
   
   # 查看日志
   docker-compose logs -f dokploy-mcp-http
   

4. MCP 客户端配置：

   stdio 模式（Claude Desktop、VS Code 等）：

   {
     "mcpServers": {
       "dokploy-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "DOKPLOY_URL=https://your-dokploy-server.com/api",
           "-e",
           "DOKPLOY_API_KEY=your_token_here",
           "dokploy-mcp"
         ]
       }
     }
   }
   

   HTTP 模式（适用于 Web 应用）：

   请先启动 HTTP 服务，然后将客户端配置为连接到 http://localhost:3000/mcp。

在 Windows 上安装

与 Linux 或 macOS 相比，Windows 上的配置略有不同。请使用 cmd 作为命令包装器：

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

环境变量

• DOKPLOY_URL：Dokploy 服务的 API URL（必需）
• DOKPLOY_API_KEY：Dokploy API 身份验证令牌（必需）

🚀 传输模式

此 MCP 服务支持多种传输模式，可满足不同的使用场景：

Stdio 模式（默认）

默认模式使用 stdio 进行直接进程间通信，非常适合桌面应用和命令行使用。

# Run with stdio (default)
npx -y @ahdev/dokploy-mcp
# or
npm run start:stdio

HTTP 模式（可流式传输的 HTTP + 旧版 SSE）

现代 HTTP 模式通过 HTTP/HTTPS 提供服务，同时支持 现代和旧版协议，以实现最大程度的兼容性：

• 可流式传输的 HTTP（MCP 2025-03-26） - 具备会话管理功能的现代协议
• 旧版 SSE（MCP 2024-11-05） - 兼容较旧的客户端

# Run with HTTP mode
npm run start:http
# or
npx -y @ahdev/dokploy-mcp --http
# or via environment variable
MCP_TRANSPORT=http npx -y @ahdev/dokploy-mcp

现代可流式传输的 HTTP 端点：

• POST /mcp - 客户端到服务端的请求
• GET /mcp - 服务端到客户端的通知
• DELETE /mcp - 终止会话
• GET /health - 健康检查端点

旧版 SSE 端点（向后兼容）：

• GET /sse - 初始化 SSE 流
• POST /messages - 发布客户端消息

配置：

• 默认端口：3000（使用 PORT=8080 覆盖）
• 同时支持现代可流式传输的 HTTP（MCP 2025-03-26）和旧版 SSE（MCP 2024-11-05）
• 两种传输类型均支持会话管理和自动清理

客户端兼容性：

现代客户端会自动使用可流式传输的 HTTP 端点，而旧版客户端可通过 SSE 端点连接。服务端可同时处理两种协议，确保兼容：

• 现代 MCP 客户端（Claude Desktop、Cline 等）→ 使用 /mcp 端点
• 旧版 MCP 客户端 → 使用 /sse 和 /messages 端点
• 自定义集成 → 根据需要选择合适的协议

有关传输模式的详细文档和客户端示例，请参阅上文的配置示例。

📚 可用工具

此 MCP 服务通过 43 个工具，分为三大类，全面支持 Dokploy 项目、应用和数据库管理：

🗂️ 项目管理（6 个工具）

完整的项目生命周期管理，包括创建、更新、复制和删除：

• project-all - 列出所有项目
• project-one - 获取项目详情
• project-create - 创建新项目
• project-update - 更新项目配置
• project-duplicate - 复制项目，并可选择性地复制服务
• project-remove - 删除项目

🚀 应用管理（24 个工具）

全面的应用生命周期和配置管理：

核心操作

• CRUD 操作：创建、读取、更新和删除应用
• 生命周期管理：部署、重新部署、启动、停止和重新加载应用
• 实用操作：在项目间移动、清理队列、刷新令牌

Git 提供商集成

支持多个 Git 提供商及其专属配置：

• GitHub 提供商 - 完整的 GitHub 集成和 Webhook
• GitLab 提供商 - 完整的 GitLab 项目集成
• Bitbucket 提供商 - Bitbucket 仓库管理
• Gitea 提供商 - 可自托管的 Gitea 集成
• Git 提供商 - 支持自定义 Git 仓库
• Docker 提供商 - 直接部署 Docker 镜像

配置管理

• 构建设置 - 配置构建类型（Dockerfile、Heroku、Nixpacks 等）
• 环境管理 - 环境变量和构建参数
• 监控集成 - 应用监控和指标
• Traefik 配置 - 负载均衡器和反向代理设置

🐘 PostgreSQL 数据库管理（13 个工具）

完整的 PostgreSQL 数据库生命周期管理：

核心数据库操作

• CRUD 操作：创建、读取、更新和移除 PostgreSQL 数据库
• 生命周期管理：部署、启动、停止、重新加载和重建数据库
• 配置管理：外部端口、环境变量、状态更改
• 项目管理：在项目间移动数据库

可用的 PostgreSQL 工具

• postgres-create - 创建新的 PostgreSQL 数据库
• postgres-one - 获取数据库详情
• postgres-update - 更新数据库配置
• postgres-remove - 删除数据库
• postgres-deploy - 部署数据库
• postgres-start - 启动数据库实例
• postgres-stop - 停止数据库实例
• postgres-reload - 重新加载数据库配置
• postgres-rebuild - 重建数据库实例
• postgres-move - 在项目间移动数据库
• postgres-changeStatus - 更改数据库状态
• postgres-saveExternalPort - 配置外部数据库端口
• postgres-saveEnvironment - 管理数据库环境变量

有关每个工具的详细信息，包括输入架构、必填字段和使用示例，请参阅 TOOLS.md。

工具注释

所有工具都包含语义注释，帮助 MCP 客户端了解其行为：

• 只读工具（readOnlyHint: true）：仅检索数据的安全操作
• 破坏性工具（destructiveHint: true）：修改或删除资源的操作
• 创建工具（destructiveHint: false）：创建新资源的操作
• 幂等工具（idempotentHint: true）：可安全重复执行的操作
• 外部 API 工具（openWorldHint: true）：所有工具都会与 Dokploy API 交互

🏗️ 架构

Dokploy MCP 服务使用以下技术构建：

• @modelcontextprotocol/sdk：用于创建 MCP 服务并定义工具
• Node.js 和 TypeScript：作为底层运行时和编程语言
• Stdio 传输：通过标准输入/输出（stdio）与 MCP 客户端通信
• Dokploy API 集成：直接与 Dokploy 服务的 REST API 交互
• 全面的工具覆盖：完整实现所有 Dokploy 应用和项目端点
• 稳健的错误处理：集中式 HTTP 客户端，支持重试逻辑和结构化错误响应
• Schema 验证：基于 Zod 的完整输入验证，与 OpenAPI 规范一致
• 工具注解：语义注解（readOnlyHint、destructiveHint 等），帮助 MCP 客户端更好地理解工具

服务架构支持：

• 43 个工具，涵盖所有项目、应用和数据库管理操作
• 多种 Git 提供商（GitHub、GitLab、Bitbucket、Gitea、自定义 Git）
• 灵活配置，适用于构建、部署和监控
• 类型安全操作，提供全面的 TypeScript 支持

每个工具都包含输入验证、API 集成和结构化响应格式化，确保与 MCP 客户端交互一致。

🔧 开发

克隆项目并安装依赖：

git clone https://github.com/andradehenrique/dokploy-mcp.git
cd dokploy-mcp
npm install

构建：

npm run build

本地配置示例

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/dokploy-mcp/src/index.ts"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_API_KEY": "your-dokploy-api-token"
      }
    }
  }
}

使用 MCP Inspector 测试

npx -y @modelcontextprotocol/inspector npx @ahdev/dokploy-mcp

文档

• TOOLS.md - 完整的工具参考，包含 Schema 和示例
• CONTRIBUTING.md - 贡献指南

🔧 故障排除

MCP 客户端错误

1. 尝试在软件包名称后添加 @latest。

2. 确保使用 Node v18 或更高版本，以便通过 npx 使用原生 fetch 支持。

3. 检查 DOKPLOY_URL 和 DOKPLOY_API_KEY 环境变量是否已正确设置。

🤝 参与贡献

欢迎贡献！如果你想为 Dokploy MCP 服务贡献代码，请查看我们的贡献指南。

🆘 支持

如果遇到问题、有疑问或想提出功能建议，请在我们的 GitHub 仓库中提交 issue。

📄 许可证

本项目采用 MIT 许可证。