Dokploy MCP Server

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

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 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 for more info.

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

<details> <summary>Alternative: Use Bun</summary>

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

</details>

<details> <summary>Alternative: Use Deno</summary>

{
  "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_AUTH_TOKEN": "your-dokploy-api-token"
      }
    }
  }
}

</details>

Install in Windsurf

Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_AUTH_TOKEN": "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"> <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">

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

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

Install in Zed

Add this to your Zed settings.json. See Zed Context Server docs for more info.

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

Install in Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json file. See Claude Desktop MCP docs for more info.

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

Install in BoltAI

Open the "Settings" page of the app, navigate to "Plugins," and enter the following JSON:

{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-dokploy-server.com/api",
        "DOKPLOY_AUTH_TOKEN": "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:

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

2. Quick Start with Helper Script:

   Use the provided helper script for easy Docker management:

   # Run in HTTP mode (recommended for web apps)
   ./docker-examples.sh http
   
   # Run in stdio mode (for MCP clients)
   ./docker-examples.sh stdio
   
   # Use docker-compose
   ./docker-examples.sh compose-up
   
   # View available commands
   ./docker-examples.sh help
   

3. Manual Docker Commands:

   Stdio Mode (for MCP clients):

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

   HTTP Mode (for web applications):

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

4. Docker Compose:

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

   # Start HTTP service
   docker-compose up -d dokploy-mcp-http
   
   # View logs
   docker-compose logs -f dokploy-mcp-http
   

5. MCP Client Configuration:

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

   {
     "mcpServers": {
       "dokploy-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "DOKPLOY_URL=https://your-dokploy-server.com/api",
           "-e",
           "DOKPLOY_AUTH_TOKEN=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:

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

Environment Variables

• DOKPLOY_URL: Your Dokploy server API URL (required)
• DOKPLOY_AUTH_TOKEN: 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.

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

HTTP Mode (Streamable HTTP)

Modern HTTP mode exposes the server via HTTP/HTTPS using the Streamable HTTP protocol (MCP 2025-03-26). Perfect for web applications and remote clients.

# 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 Server Endpoints:

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

Configuration:

• Default port: 3000 (override with PORT=8080)
• Uses modern Streamable HTTP protocol (MCP 2025-03-26)
• Session management with automatic cleanup

For detailed transport mode documentation and client examples, see TRANSPORT_MODES.md.

📚 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.

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:

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

Build:

npm run build

Local Configuration Example

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

Testing with MCP Inspector

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

Documentation

• TOOLS.md - Complete tool reference with schemas and examples
• 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_AUTH_TOKEN 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.

🆘 Support

If you encounter any issues, have questions, or want to suggest a feature, please open an issue in our GitHub repository.

📄 License

This project is licensed under the MIT License.