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.

1. Build the Docker Image:

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

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

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:

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

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 MIT License.