dokploy-mcp

KO | EN

gitlite — search

#python #react #llm #go #android #linux #java #windows #awesome #cli #kubernetes #vue #pytorch #ios

(★ 18)

Dokploy MCP Server exposes Dokploy functionalities as tools consumable via the Model Context Protocol (MCP)

dokploy-mcp 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Dokploy MCP Server

> **⚠️ PROJECT DISCONTINUED**
>
> This project has been moved to the official Dokploy organization and will no longer be maintained in this repository.
>
> **📍 New official repository:** https://github.com/Dokploy/mcp
>
> Please migrate to the official repository to receive the latest updates and ongoing support.

---

![Discontinued](https://img.shields.io/badge/Status-DISCONTINUED-red?style=for-the-badge) [![New Repository](https://img.shields.io/badge/New_Repo-Dokploy%2Fmcp-blue?style=for-the-badge)](https://github.com/Dokploy/mcp)

[![npm version](https://img.shields.io/npm/v/@ahdev/dokploy-mcp.svg)](https://www.npmjs.com/package/@ahdev/dokploy-mcp) [<img alt="Install in 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 Server exposes Dokploy functionalities as tools consumable via the Model Context Protocol (MCP). It allows MCP-compatible clients (e.g., AI models, other applications) to interact with your Dokploy server programmatically.

**🚨 This project is no longer maintained. Please migrate to the official repository immediately.**

📖 **[Migration Guide →](./MIGRATION.md)** | 🔗 **[Official Repository →](https://github.com/Dokploy/mcp)**

This server focuses exclusively on **tools** for direct Dokploy API operations, providing a clean and efficient interface for project and application management.

## 🛠️ Getting Started

### Requirements

- Node.js >= v18.0.0 (or Docker)
- Cursor, VS Code, Claude Desktop, or another MCP Client
- A running Dokploy server instance

### Install in Cursor

Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`

Add this to your Cursor `~/.cursor/mcp.json` file. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.

```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>Alternative: Use 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>Alternative: Use 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>

### Install in Windsurf

Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.

```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"
      }
    }
  }
}
```

### Install in VS Code

[<img alt="Install in 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="Install in 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)

Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.

```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"
      }
    }
  }
}
```

### Install in Zed

Add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.

```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"
      }
    }
  }
}
```

### Install in Claude Desktop

Add this to your Claude Desktop `claude_desktop_config.json` file. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.

```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"
      }
    }
  }
}
```

### Install in BoltAI

Open the "Settings" page of the app, navigate to "Plugins," and enter the following 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"
      }
    }
  }
}
```

### Using Docker

The Docker container supports both **stdio** and **HTTP** transport modes, making it flexible for different deployment scenarios.

1.  **Build the Docker Image:**

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

2.  **Manual Docker Commands:**

**Stdio Mode (for MCP clients):**

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

**HTTP Mode (for web applications):**

```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:**

Use the provided `docker-compose.yml` for production deployments:

```bash
    # Start HTTP service
    docker-compose up -d dokploy-mcp-http

# View logs
    docker-compose logs -f dokploy-mcp-http
    ```

4.  **MCP Client Configuration:**

**For stdio mode (Claude Desktop, VS Code, etc.):**

```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"
          ]
        }
      }
    }
    ```

**For HTTP mode (web applications):**

Start the HTTP server first, then configure your client to connect to `http://localhost:3000/mcp`.

### Install in Windows

The configuration on Windows is slightly different compared to Linux or macOS. Use `cmd` as the command wrapper:

```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"
      }
    }
  }
}
```

### Environment Variables

- `DOKPLOY_URL`: Your Dokploy server API URL (required)
- `DOKPLOY_API_KEY`: Your Dokploy API authentication token (required)

## 🚀 Transport Modes

This MCP server supports multiple transport modes to suit different use cases:

### Stdio Mode (Default)

The default mode uses stdio for direct process communication, ideal for desktop applications and command-line usage.

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

### HTTP Mode (Streamable HTTP + Legacy SSE)

Modern HTTP mode exposes the server via HTTP/HTTPS supporting **both modern and legacy protocols** for maximum compatibility:

- **Streamable HTTP (MCP 2025-03-26)** - Modern protocol with session management
- **Legacy SSE (MCP 2024-11-05)** - Backwards compatibility for older clients

```bash
# 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
```

**Modern Streamable HTTP Endpoints:**

- **POST /mcp** - Client-to-server requests
- **GET /mcp** - Server-to-client notifications
- **DELETE /mcp** - Session termination
- **GET /health** - Health check endpoint

**Legacy SSE Endpoints (Backwards Compatibility):**

- **GET /sse** - SSE stream initialization
- **POST /messages** - Client message posting

**Configuration:**

- Default port: `3000` (override with `PORT=8080`)
- Supports both modern Streamable HTTP (MCP 2025-03-26) and legacy SSE (MCP 2024-11-05)
- Session management with automatic cleanup for both transport types

**Client Compatibility:**

Modern clients automatically use the Streamable HTTP endpoints, while legacy clients can connect using the SSE endpoints. The server handles both protocols simultaneously, ensuring compatibility with:

- **Modern MCP clients** (Claude Desktop, Cline, etc.) → Use `/mcp` endpoints
- **Legacy MCP clients** → Use `/sse` and `/messages` endpoints
- **Custom integrations** → Choose the appropriate protocol for your needs

For detailed transport mode documentation and client examples, refer to the configuration examples above.

## 📚 Available Tools

This MCP server provides comprehensive tools for Dokploy project, application, and database management through **43 tools** organized into three main categories:

### 🗂️ Project Management (6 tools)

Complete project lifecycle management including creation, updates, duplication, and deletion:

- **`project-all`** - List all projects
- **`project-one`** - Get project details
- **`project-create`** - Create new projects
- **`project-update`** - Update project configurations
- **`project-duplicate`** - Duplicate projects with selective service copying
- **`project-remove`** - Delete projects

### 🚀 Application Management (24 tools)

Comprehensive application lifecycle and configuration management:

#### Core Operations

- **CRUD Operations**: Create, read, update, delete applications
- **Lifecycle Management**: Deploy, redeploy, start, stop, reload applications
- **Utility Operations**: Move between projects, clean queues, refresh tokens

#### Git Provider Integrations

Support for multiple Git providers with specific configurations:

- **GitHub Provider** - Full GitHub integration with webhooks
- **GitLab Provider** - Complete GitLab project integration
- **Bitbucket Provider** - Bitbucket repository management
- **Gitea Provider** - Self-hosted Gitea integration
- **Git Provider** - Custom Git repository support
- **Docker Provider** - Direct Docker image deployment

#### Configuration Management

- **Build Settings** - Configure build types (Dockerfile, Heroku, Nixpacks, etc.)
- **Environment Management** - Environment variables and build arguments
- **Monitoring Integration** - Application monitoring and metrics
- **Traefik Configuration** - Load balancer and reverse proxy settings

### 🐘 PostgreSQL Database Management (13 tools)

Complete PostgreSQL database lifecycle management:

#### Core Database Operations

- **CRUD Operations**: Create, read, update, remove PostgreSQL databases
- **Lifecycle Management**: Deploy, start, stop, reload, rebuild databases
- **Configuration Management**: External ports, environment variables, status changes
- **Project Management**: Move databases between projects

#### Available PostgreSQL Tools

- **`postgres-create`** - Create new PostgreSQL databases
- **`postgres-one`** - Get database details
- **`postgres-update`** - Update database configurations
- **`postgres-remove`** - Delete databases
- **`postgres-deploy`** - Deploy databases
- **`postgres-start`** - Start database instances
- **`postgres-stop`** - Stop database instances
- **`postgres-reload`** - Reload database configurations
- **`postgres-rebuild`** - Rebuild database instances
- **`postgres-move`** - Move databases between projects
- **`postgres-changeStatus`** - Change database status
- **`postgres-saveExternalPort`** - Configure external database ports
- **`postgres-saveEnvironment`** - Manage database environment variables

For detailed information about each tool, including input schemas, required fields, and usage examples, see **[TOOLS.md](TOOLS.md)**.

### Tool Annotations

All tools include semantic annotations to help MCP clients understand their behavior:

- **Read-Only Tools** (`readOnlyHint: true`): Safe operations that only retrieve data
- **Destructive Tools** (`destructiveHint: true`): Operations that modify or delete resources
- **Creation Tools** (`destructiveHint: false`): Operations that create new resources
- **Idempotent Tools** (`idempotentHint: true`): Operations safe to repeat
- **External API Tools** (`openWorldHint: true`): All tools interact with Dokploy API

## 🏗️ Architecture

The Dokploy MCP Server is built using:

- **`@modelcontextprotocol/sdk`**: For creating the MCP server and defining tools
- **Node.js & TypeScript**: As the underlying runtime and language
- **Stdio Transport**: Communicates with MCP clients over standard input/output (stdio)
- **Dokploy API Integration**: Direct interaction with Dokploy server's REST API
- **Comprehensive Tool Coverage**: Complete implementation of all Dokploy application and project endpoints
- **Robust Error Handling**: Centralized HTTP client with retry logic and structured error responses
- **Schema Validation**: Full Zod-based input validation matching OpenAPI specifications
- **Tool Annotations**: Semantic annotations (readOnlyHint, destructiveHint, etc.) for enhanced MCP client understanding

The server architecture supports:

- **43 Tools** covering all project, application, and database management operations
- **Multiple Git Providers** (GitHub, GitLab, Bitbucket, Gitea, custom Git)
- **Flexible Configuration** for builds, deployments, and monitoring
- **Type-Safe Operations** with comprehensive TypeScript support

Each tool includes input validation, API integration, and structured response formatting for consistent MCP client interaction.

## 🔧 Development

Clone the project and install dependencies:

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

Build:

```bash
npm run build
```

### Local Configuration Example

```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"
      }
    }
  }
}
```

### Testing with MCP Inspector

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

### Documentation

- **[TOOLS.md](TOOLS.md)** - Complete tool reference with schemas and examples
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contributing guidelines

## 🔧 Troubleshooting

### MCP Client Errors

1. Try adding `@latest` to the package name.

2. Make sure you are using Node v18 or higher to have native fetch support with `npx`.

3. Verify your `DOKPLOY_URL` and `DOKPLOY_API_KEY` environment variables are correctly set.

## 🤝 Contributing

We welcome contributions! If you'd like to contribute to the Dokploy MCP Server, please check out our [Contributing Guide](CONTRIBUTING.md).

## 🆘 Support

If you encounter any issues, have questions, or want to suggest a feature, please [open an issue](https://github.com/andradehenrique/dokploy-mcp/issues) in our GitHub repository.

## 📄 License

This project is licensed under the [MIT License](LICENSE).

dokploy-mcp

dokploy-mcp 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

dokploy-mcp

dokploy-mcp 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README