内容
# Dokploy MCP 服务器
> **⚠️ 项目已停止维护**
>
> 该项目已转移到官方 Dokploy 组织，不再在此仓库中维护。
>
> **📍 新官方仓库：** https://github.com/Dokploy/mcp
>
> 请迁移到官方仓库以接收最新的更新和持续的支持。
---
 [](https://github.com/Dokploy/mcp)
[](https://www.npmjs.com/package/@ahdev/dokploy-mcp) [<img alt="在 VS Code 中安装 (npx)" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Dokploy%20MCP&color=0098FF">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)
Dokploy MCP 服务器通过模型上下文协议（MCP）公开 Dokploy 功能，使 MCP 兼容的客户端（例如 AI 模型、其他应用程序）能够以编程方式与您的 Dokploy 服务器交互。
**🚨 该项目不再维护。请立即迁移到官方仓库。**
📖 **[迁移指南 →](./MIGRATION.md)** | 🔗 **[官方仓库 →](https://github.com/Dokploy/mcp)**
该服务器专门关注用于直接 Dokploy API 操作的**工具**，提供干净高效的项目和应用程序管理接口。
## 🛠️ 入门指南
### 要求
- Node.js >= v18.0.0（或 Docker）
- Cursor、VS Code、Claude Desktop 或另一个 MCP 客户端
- 一个正在运行的 Dokploy 服务器实例
### 在 Cursor 中安装
前往：`设置` -> `Cursor 设置` -> `MCP` -> `添加新的全局 MCP 服务器`
将以下内容添加到您的 Cursor `~/.cursor/mcp.json` 文件中。您也可以在特定项目中安装，方法是创建项目文件夹中的 `.cursor/mcp.json`。更多信息请参阅 [Cursor MCP 文档](https://docs.cursor.com/context/model-context-protocol)。
```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"
}
}
}
}
```
<details>
<summary>替代方案：使用 Bun</summary>
```json
{
"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"
}
}
}
}
```
</details>
<details>
<summary>替代方案：使用 Deno</summary>
```json
{
"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"
}
}
}
}
```
</details>
### 在 Windsurf 中安装
将以下内容添加到您的 Windsurf MCP 配置文件中。更多信息请参阅 [Windsurf MCP 文档](https://docs.windsurf.com/windsurf/mcp)。
```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"
}
}
}
}
```
### 在 VS Code 中安装
[<img alt="在 VS Code 中安装 (npx)" src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Dokploy%20MCP&color=0098FF">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)
[<img alt="在 VS Code Insiders 中安装 (npx)" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Dokploy%20MCP&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22dokploy-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40ahdev%2Fdokploy-mcp%40latest%22%5D%7D)
将以下内容添加到您的 VS Code MCP 配置文件中。更多信息请参阅 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。
```json
{
"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 文档](https://zed.dev/docs/assistant/context-servers)。
```json
{
"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 文档](https://modelcontextprotocol.io/quickstart/user)。
```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"
}
}
}
}
```
### 在 BoltAI 中安装
打开应用程序的“设置”页面，导航到“插件”，并输入以下 JSON：
```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 镜像：**
```bash
git clone https://github.com/andradehenrique/dokploy-mcp.git
cd dokploy-mcp
docker build -t dokploy-mcp .
```
2. **手动 Docker 命令：**
**stdio 模式（适用于 MCP 客户端）：**
```bash
docker run -it --rm \
-e DOKPLOY_URL=https://your-dokploy-server.com/api \
-e DOKPLOY_API_KEY=your_token_here \
dokploy-mcp
```
**HTTP 模式（适用于 Web 应用程序）：**
```bash
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` 进行生产部署：
```bash
# 启动 HTTP 服务
docker-compose up -d dokploy-mcp-http
# 查看日志
docker-compose logs -f dokploy-mcp-http
```
4. **MCP 客户端配置：**
**适用于 stdio 模式（Claude Desktop、VS Code 等）：**
```json
{
"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 上安装
Windows 上的配置与 Linux 或 macOS 略有不同。使用 `cmd` 作为命令包装器：
```json
{
"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 进行直接进程通信，适用于桌面应用程序和命令行用法。
```bash
# 使用 stdio（默认）运行
npx -y @ahdev/dokploy-mcp
# 或
npm run start:stdio
```
### HTTP 模式（可流式 HTTP + 旧版 SSE）
现代 HTTP 模式通过 HTTP/HTTPS 公开服务器，支持 **现代和旧版协议** 以实现最大兼容性：
- **可流式 HTTP（MCP 2025-03-26）** - 现代协议，会话管理
- **旧版 SSE（MCP 2024-11-05）** - 旧客户端的向后兼容性
```bash
# 使用 HTTP 模式运行
npm run start:http
# 或
npx -y @ahdev/dokploy-mcp --http
# 或通过环境变量
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 集成，带有 Webhooks
- **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](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 客户端
- **模式验证**：基于 Zod 的完整输入验证，匹配 OpenAPI 规范
- **工具注释**：语义注释（readOnlyHint、destructiveHint 等），以便 MCP 客户端更好地理解
服务器架构支持：
- **43 种工具**，涵盖所有项目、应用程序和数据库管理操作
- **多个 Git 提供商**（GitHub、GitLab、Bitbucket、Gitea、自定义 Git）
- **灵活的配置**，适用于构建、部署和监控
- **类型安全的运算**，具有全面的 TypeScript 支持
每个工具都包含输入验证、API 集成和结构化响应格式化，以便与 MCP 客户端进行一致的交互。
## 🔧 开发
克隆项目并安装依赖项：
```bash
git clone https://github.com/andradehenrique/dokploy-mcp.git
cd dokploy-mcp
npm install
```
构建：
```bash
npm run build
```
### 本地配置示例
```json
{
"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 检视器进行测试
```bash
npx -y @modelcontextprotocol/inspector npx @ahdev/dokploy-mcp
```
### 文档
- **[TOOLS.md](TOOLS.md)** - 完整的工具参考，包含模式和示例
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - 贡献指南
## 🔧 故障排除
### MCP 客户端错误
1. 尝试在包名后添加 `@latest`。
2. 确保您使用的是 Node v18 或更高版本，以支持 `npx` 原生 fetch。
3. 验证您的 `DOKPLOY_URL` 和 `DOKPLOY_API_KEY` 环境变量是否正确设置。
## 🤝 贡献
我们欢迎贡献！如果您想为 Dokploy MCP 服务器做出贡献，请查看我们的 [贡献指南](CONTRIBUTING.md)。
## 🆘 支持
如果您遇到任何问题、疑问或需要建议功能，请在我们的 GitHub 仓库中 [开启一个问题](https://github.com/andradehenrique/dokploy-mcp/issues)。
## 📄 许可
该项目根据 [MIT 许可协议](LICENSE) 进行许可。
MCP 市场
