dokploy-mcp

MCP server for Dokploy — enables AI assistants to manage Dokploy deployments through the Model Context Protocol.

Purpose

dokploy-mcp is a platform adapter that exposes Dokploy's REST API as MCP tools and resources. It enables AI coding assistants (Claude Code, OpenCode, Codex, and others) to inspect, create, configure, and monitor deployments on Dokploy without requiring the user to navigate the Dokploy dashboard.

Why It Exists

Dokploy provides powerful deployment capabilities including Docker-in-Docker, persistent volumes, and managed databases. When AI assistants can programmatically interact with Dokploy, they can:

• Inspect a codebase and recommend a deployment strategy (project detection)
• Generate a deploy.intent.yaml manifest
• Create applications with correct settings automatically
• Configure environment variables, domains, and secrets
• Trigger deployments and poll for status
• Validate Docker Compose configurations before deployment

This MCP server bridges the gap between an AI assistant's natural language understanding and Dokploy's API-driven deployment platform.

Key Features

• 12 MCP tools (8 read-only, 4 mutating)
• Project detection — analyzes local code to recommend build strategy
• Read/write separation — read-only tools safe for exploration; mutating tools require confirmation
• Docker Compose validation — validate compose files before deployment
• Production readiness recommendations — built-in guidance for production deployments
• Zod schema validation — all tool inputs validated, clear error messages

Architecture Summary

┌─────────────────┐     MCP       ┌──────────────────┐     REST API     ┌─────────────┐
│  AI Assistant   │◄──────────────►│    dokploy-mcp    │◄─────────────────►│   Dokploy   │
│                 │                │   (TypeScript)    │                   │   Server    │
└─────────────────┘                └──────────────────┘                   └─────────────┘

Components

Component	Location	Purpose
MCP Server	src/server/	Protocol handler, tool routing
Tools	src/tools/	12 tool implementations (8 read-only, 4 mutating)
API Client	src/adapters/dokploy-api/	Dokploy API client with x-api-key auth
Project Detection	src/detection/	Local codebase analysis + production recommendations
Schemas	src/schemas/	TypeScript types + Zod validation

Supported Tools

Read-Only Tools (8)

Tool	Description
list_projects	List all Dokploy projects
get_project	Get a specific project
list_applications	List applications with filtering
get_application	Get application details
list_domains	List domains for an app or compose
get_logs	Get deployment logs
validate_compose	Validate docker-compose.yml syntax
recommend_build_strategy	Analyze project, recommend best deployment type

Mutating Tools (4)

Tool	Description
create_application	Create a new application
update_application	Update application configuration
assign_domain	Assign custom domain with HTTPS
trigger_deploy	Trigger deployment

Project Structure

dokploy-mcp/
├── src/
│   ├── server/                  # MCP server implementation
│   ├── tools/                   # Tool definitions (read-only vs mutating)
│   ├── adapters/dokploy-api/     # Dokploy API client
│   ├── detection/               # Project type detection + production recommendations
│   ├── schemas/                 # TypeScript + Zod schemas
│   └── prompts/                 # Prompt templates
├── docs/
│   ├── dokploy-api-mapping.md   # Tool → API endpoint mapping
│   └── production-guidance.md   # Production best practices
├── examples/                     # JSON example payloads
├── tests/                       # Unit and integration tests
├── package.json
└── README.md

Installation

Prerequisites

• Node.js 18+
• A running Dokploy instance
• Dokploy API key

Build from Source

git clone https://github.com/REPLACE_WITH_ORG/dokploy-mcp
cd dokploy-mcp
npm install
npm run build

Configuration

Environment Variables

export DOKPLOY_URL="http://your-dokploy-instance:3000"
export DOKPLOY_API_KEY="your-api-key"

Claude Code Setup

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "dokploy": {
      "command": "node",
      "args": ["./path/to/dokploy-mcp/dist/server.js"],
      "env": {
        "DOKPLOY_URL": "http://your-dokploy:3000",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}

Examples

Deploy a Git-Based Application

import { createServer } from 'dokploy-mcp'

const server = await createServer()

// Create application
const app = await server.handleToolCall('create_application', {
  projectId: 'proj_xxxxxxxx',
  name: 'my-node-app',
  appType: 'git',
  gitProvider: 'github',
  repository: 'owner/my-node-app',
  branch: 'main',
  buildType: 'nixpacks',
  exposePort: 3000
})

// Assign domain
await server.handleToolCall('assign_domain', {
  applicationId: app.application.id,
  fqdn: 'app.example.com',
  https: true
})

// Trigger deployment
await server.handleToolCall('trigger_deploy', {
  applicationId: app.application.id
})

Validate Docker Compose

const validation = await server.handleToolCall('validate_compose', {
  composeFile: `version: '3.8'
services:
  web:
    image: nginx
`
})

console.log('Valid:', validation.valid)
console.log('Warnings:', validation.warnings)

Analyze Project for Production

const analysis = await server.handleToolCall('recommend_build_strategy', {
  projectPath: '/path/to/my-project'
})

console.log('Detected:', analysis.detection.kind)
console.log('Production-ready:', analysis.production.recommended)
console.log('Warnings:', analysis.production.warnings)

Example Payloads

JSON example files matching actual API schemas are in examples/:

File	Description
examples/create-source-app.json	create_application payload (git/nixpacks app)
examples/create-dockerfile-app.json	create_application payload (dockerfile app)
examples/create-compose-app.json	create_application payload (compose app)
examples/set-env-vars.json	update_application env var payload
examples/trigger-deploy.json	trigger_deploy payload
examples/get-application.json	get_application payload
examples/get-logs.json	get_logs payload

All example files are sanitized — no real credentials or endpoint references. Replace all placeholder IDs before use.

Test Fixtures

Realistic project fixtures for testing detection and validation:

File	Description
fixtures/valid-manifest.yaml	Complete valid deploy.intent.yaml
fixtures/invalid-manifest.yaml	Manifest with intentional errors (for validation testing)
fixtures/package.json	Node.js package.json with Express + TypeScript
fixtures/Dockerfile	Multi-stage production Dockerfile
fixtures/docker-compose.yml	Multi-service compose (web, api, worker, db, redis)
fixtures/monorepo-package.json	Monorepo root with pnpm workspaces

Safety & Deployment Risks

Risk	Mitigation
Docker-in-Docker resource usage	Set memoryLimit and cpuLimit; warn about resource-intensive builds
Persistent volume data loss	Always include ephemeral: false for persistent data; document volume requirements
Production misconfiguration	Production recommendations warn about common issues
Secret exposure	API key passed via x-api-key header; never logged
Compose validation bypass	Validate compose files before deployment; warn about missing health checks

Documentation Accuracy Note

The official Dokploy documentation remains the source of truth for all platform behavior, API endpoints, authentication details, and configuration options.

This repository provides a platform adapter — it wraps Dokploy's REST API as MCP tools for use by AI assistants. The docs/dokploy-api-mapping.md file documents which endpoints this adapter calls and how. It does not replace the official Dokploy API reference.

Limitations

• No support for database deployments (one-click databases)
• No support for automatic rollback configuration
• No support for cluster/multi-server deployments
• No webhook subscription for real-time events
• Single Dokploy instance
• Requires API key with full project/application permissions

Roadmap

• Add rollback tool
• Add database management tools (PostgreSQL, MySQL, Redis, MongoDB)
• Add cluster/multi-server support
• Add webhook subscription for real-time events
• Add metrics endpoints

Related Repositories

• coolify-mcp — MCP server for Coolify
• claude-skill-autodeploy — Claude Code deployment skill
• opencode-skill-autodeploy — OpenCode deployment skill
• codex-skill-autodeploy — Codex deployment skill

License

MIT License — see LICENSE file for details.