Skip to main content

​
Prerequisites

Before you begin, make sure you have:
Completed the Installation guide for your MCP client
Your Dokploy server URL and API key ready
Your MCP client (Cursor, VS Code, Claude Desktop, etc.) running

​
Step-by-Step Guide

1

Verify Installation

First, let’s verify that Dokploy MCP Server is properly installed and connected to your Dokploy instance.In your MCP client, try asking:
List all my Dokploy projects
This will use the project-all tool to retrieve all projects from your Dokploy server.Expected output:
[
  {
    "projectId": "proj_abc123",
    "name": "Production Apps",
    "description": "Production environment applications",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "projectId": "proj_def456",
    "name": "Staging",
    "description": "Staging environment",
    "createdAt": "2024-02-01T14:20:00Z"
  }
]
If you get an error, check your environment variables in the installation config and ensure your Dokploy server is accessible.
2

Create Your First Project

Let’s create a new project to organize your applications.Ask your MCP client:
Create a new Dokploy project called "My First App" with description "Getting started with Dokploy MCP"
This uses the project-create tool:
{
  "name": "My First App",
  "description": "Getting started with Dokploy MCP"
}
Expected output:
{
  "projectId": "proj_xyz789",
  "name": "My First App",
  "description": "Getting started with Dokploy MCP",
  "createdAt": "2024-03-04T16:45:00Z"
}
Save the projectId - you’ll need it for creating applications in this project.
3

Create an Application

Now let’s create an application within your project.Ask your MCP client:
Create a new application named "hello-world" in project proj_xyz789
This uses the application-create tool:
{
  "name": "hello-world",
  "appName": "hello-world",
  "projectId": "proj_xyz789"
}
Expected output:
{
  "applicationId": "app_123abc",
  "name": "hello-world",
  "appName": "hello-world",
  "projectId": "proj_xyz789",
  "applicationStatus": "idle",
  "createdAt": "2024-03-04T16:50:00Z"
}
4

Configure Git Provider

Connect your application to a Git repository. Here’s an example with GitHub:Ask your MCP client:
Configure GitHub provider for application app_123abc with repository "username/hello-world", branch "main", and owner "username"
This uses the application-saveGithubProvider tool:
{
  "applicationId": "app_123abc",
  "repository": "hello-world",
  "branch": "main",
  "owner": "username",
  "githubId": "github_connection_id",
  "enableSubmodules": false
}
You can also use GitLab (application-saveGitlabProvider), Bitbucket (application-saveBitbucketProvider), Gitea (application-saveGiteaProvider), or a custom Git server (application-saveGitProvider).
Alternative: Deploy from Docker ImageIf you prefer to deploy from a Docker image instead:
Configure Docker provider for application app_123abc with image "nginx:alpine"
This uses the application-saveDockerProvider tool:
{
  "applicationId": "app_123abc",
  "dockerImage": "nginx:alpine"
}
5

Set Build Configuration (Optional)

If you’re building from source, configure the build type:
Set build type for application app_123abc to dockerfile
This uses the application-saveBuildType tool:
{
  "applicationId": "app_123abc",
  "buildType": "dockerfile"
}
Build types available:
  • dockerfile - Build using Dockerfile
  • nixpacks - Auto-detect and build with Nixpacks
  • buildpacks - Use Cloud Native Buildpacks
  • heroku - Heroku buildpacks
  • docker - Use pre-built Docker image
6

Configure Environment Variables

Add environment variables for your application:
Set environment variables for application app_123abc
This uses the application-saveEnvironment tool:
{
  "applicationId": "app_123abc",
  "env": "PORT=3000\nNODE_ENV=production\nAPI_KEY=your-secret-key"
}
Environment variables are passed as a single string with \n separating each variable. Each line should follow the format KEY=value.
7

Deploy Your Application

Now let’s deploy the application:
Deploy application app_123abc
This uses the application-deploy tool:
{
  "applicationId": "app_123abc"
}
Expected output:
{
  "success": true,
  "message": "Application deployment started",
  "applicationId": "app_123abc"
}
The deployment process will:
  1. Clone your repository (or pull the Docker image)
  2. Build the application (if using source code)
  3. Start the container
  4. Configure networking and routing
8

Monitor Deployment Status

Check the status of your application:
Get details for application app_123abc
This uses the application-one tool:
{
  "applicationId": "app_123abc"
}
Expected output:
{
  "applicationId": "app_123abc",
  "name": "hello-world",
  "appName": "hello-world",
  "applicationStatus": "running",
  "buildType": "dockerfile",
  "repository": "hello-world",
  "branch": "main",
  "owner": "username"
}
You can also read monitoring data with application-readAppMonitoring to get resource usage metrics.
9

Configure a Domain (Optional)

Add a domain to access your application:
Create a domain for application app_123abc with host "hello-world.yourdomain.com" and enable HTTPS with Let's Encrypt
This uses the domain-create tool:
{
  "host": "hello-world.yourdomain.com",
  "applicationId": "app_123abc",
  "https": true,
  "certificateType": "letsencrypt",
  "port": 3000,
  "domainType": "application",
  "stripPath": false
}
Expected output:
{
  "domainId": "dom_456def",
  "host": "hello-world.yourdomain.com",
  "https": true,
  "certificateType": "letsencrypt",
  "applicationId": "app_123abc"
}
Dokploy will automatically request and configure an SSL certificate from Let’s Encrypt. Make sure your DNS is properly configured to point to your Dokploy server.

​
Common Operations

​
Managing Application Lifecycle

Stop application app_123abc

​
Working with Databases

Create a PostgreSQL database:
Create a PostgreSQL database named "my-database" in project proj_xyz789 with database name "appdb", user "appuser", and password "secure-password"
Uses postgres-create tool:
{
  "name": "my-database",
  "appName": "my-database",
  "databaseName": "appdb",
  "databaseUser": "appuser",
  "databasePassword": "secure-password",
  "projectId": "proj_xyz789",
  "dockerImage": "postgres:16-alpine"
}
Deploy the database:
Deploy PostgreSQL database postgres_789xyz

​
Managing Domains

List all domains for application app_123abc

​
Example: Complete Application Deployment

Here’s a complete workflow combining multiple operations: 
1. Create a new project called "Production API"
2. Create an application named "api-server" in that project
3. Configure GitHub provider with repository "myorg/api-server", branch "main"
4. Set build type to dockerfile
5. Add environment variables: DATABASE_URL=postgresql://..., JWT_SECRET=...
6. Create a PostgreSQL database named "api-db" in the same project
7. Deploy the database
8. Deploy the application
9. Create a domain "api.mycompany.com" with Let's Encrypt SSL
10. Show me the application status
Your MCP client will execute all these operations using the appropriate tools in sequence.

​
Next Steps

Now that you’ve deployed your first application, explore the full capabilities:

API Reference

Explore all 67 tools with detailed schemas and examples

Projects

Learn about project management tools

Applications

Master application deployment and configuration

Domains

Configure domains and SSL certificates

​
Tips and Best Practices

Use natural language: You don’t need to remember exact tool names. Just describe what you want to do, and your MCP client will figure out which tools to use.
Check status before operations: Always verify the current state with tools like project-all, application-one, or postgres-one before making changes.
Test in staging first: Create separate projects for staging and production environments to test deployments safely.
Destructive operations: Tools marked with destructiveHint: true (like delete, stop, and remove) cannot be undone. Always verify IDs before running destructive operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us