Dokploy MCP Server

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.

Install in Windsurf

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

Install in VS Code

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

Install in Zed

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

Install in Claude Desktop

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

Install in BoltAI

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

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/Dokploy/mcp.git cd dokploy-mcp docker build -t dokploy-mcp .

2. 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 8080: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:

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

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

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.

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

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:

• Internal port: 3000 (fixed)

• External port: configurable via EXTERNAL_PORT (default: 3000)

• 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 67 tools organized into five main categories:

🗂️ Project Management (6 tools)

• project-all - List all projects

• project-one - Get project by ID

• project-create - Create new project

• project-update - Update project configuration

• project-duplicate - Duplicate project with optional service selection

• project-remove - Delete project

🚀 Application Management (26 tools)

Core Operations:

• application-one, application-create, application-update, application-delete

• application-deploy, application-redeploy, application-start, application-stop, application-reload

• application-move, application-markRunning, application-cancelDeployment

Git Providers:

• application-saveGithubProvider, application-saveGitlabProvider, application-saveBitbucketProvider

• application-saveGiteaProvider, application-saveGitProvider, application-disconnectGitProvider

Configuration:

• application-saveBuildType, application-saveEnvironment, application-saveDockerProvider

• application-readAppMonitoring, application-readTraefikConfig, application-updateTraefikConfig

• application-refreshToken, application-cleanQueues

🌐 Domain Management (9 tools)

• domain-byApplicationId - List domains by application ID

• domain-byComposeId - List domains by compose service ID

• domain-one - Get domain by ID

• domain-create - Create domain (application/compose/preview)

• domain-update - Update domain configuration

• domain-delete - Delete domain

• domain-validateDomain - Validate domain DNS/target

• domain-generateDomain - Suggest a domain for an app

• domain-canGenerateTraefikMeDomains - Check Traefik.me availability on a server

🐘 PostgreSQL Database Management (13 tools)

Core Operations:

• postgres-create, postgres-one, postgres-update, postgres-remove, postgres-move

• postgres-deploy, postgres-start, postgres-stop, postgres-reload, postgres-rebuild

Configuration:

• postgres-changeStatus, postgres-saveExternalPort, postgres-saveEnvironment

🐬 MySQL Database Management (13 tools)

Core Operations:

• mysql-create, mysql-one, mysql-update, mysql-remove, mysql-move

• mysql-deploy, mysql-start, mysql-stop, mysql-reload, mysql-rebuild

Configuration:

• mysql-changeStatus, mysql-saveExternalPort, mysql-saveEnvironment

Tool Annotations: All tools include semantic annotations (readOnlyHint, destructiveHint, idempotentHint) to help MCP clients understand their behavior and safety characteristics.

For detailed schemas, parameters, and usage examples, see TOOLS.md.

🏗️ Architecture

Built with @modelcontextprotocol/sdk, TypeScript, and Zod for type-safe schema validation:

• 67 Tools covering projects, applications, domains, PostgreSQL, and MySQL management

• Multiple Transports: Stdio (default) and HTTP (Streamable HTTP + legacy SSE)

• Multiple Git Providers: GitHub, GitLab, Bitbucket, Gitea, custom Git

• Robust Error Handling: Centralized API client with retry logic

• Type Safety: Full TypeScript support with Zod schema validation

• Tool Annotations: Semantic hints for MCP client behavior understanding

🔧 Development

Clone the project and install dependencies:

Build:

Local Configuration Example

Testing with MCP Inspector

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_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 Apache License.