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.

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 → | 🔗 Official Repository →

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

Alternative: Use Bun

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

Alternative: Use Deno

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

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

Install in VS Code

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_API_KEY": "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_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 for more info.

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

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

Build the Docker Image:

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

Manual Docker Commands:

Stdio Mode (for MCP clients):

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):

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

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

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_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:

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

# 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

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

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

Try adding @latest to the package name.
Make sure you are using Node v18 or higher to have native fetch support with npx.
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.

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