Installation

Prerequisites

Before installing Dokploy MCP Server, ensure you have:

Node.js or Docker

Node.js >= v18.0.0 for native fetch support with npx, or Docker for containerized deployment

Dokploy Server

A running Dokploy instance with API access. You’ll need:

Your Dokploy server URL (e.g., https://your-dokploy-server.com/api)
A valid API key/token from your Dokploy account

MCP Client

One of the supported MCP clients: Cursor, VS Code, Windsurf, Zed, Claude Desktop, or BoltAI

Installation by Client

Install in Cursor

Go to: Settings → Cursor Settings → MCP → Add new global MCP server
Add this configuration to your Cursor ~/.cursor/mcp.json file:

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

Replace your-dokploy-server.com/api with your Dokploy API URL
Replace your-dokploy-api-token with your API key

Project-specific installation

You can also install in a specific project by creating .cursor/mcp.json in your project folder instead of using the global config.

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 VS Code

Quick install: Click the badge below to install automatically

Manual Installation:

Add this to your VS Code MCP config file:

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

Replace the environment variables with your Dokploy credentials

See VS Code MCP docs for more information.

Install in Windsurf

Add this to your Windsurf MCP config file:

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

Replace the environment variables with your Dokploy credentials

See Windsurf MCP docs for more information.

Install in Zed

Add this to your Zed settings.json:

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

Replace the settings values with your Dokploy credentials

See Zed Context Server docs for more information.

Install in Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json file:

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

Replace the environment variables with your Dokploy credentials

See Claude Desktop MCP docs for more information.

Install in BoltAI

Open the “Settings” page of the app
Navigate to “Plugins”
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"
      }
    }
  }
}

Replace the environment variables with your Dokploy credentials

Docker Installation

The Docker container supports both stdio and HTTP transport modes for flexible deployment.

Clone and Build

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

Run in Stdio Mode

For MCP clients that use stdio transport:

docker run -it --rm \
  -e DOKPLOY_URL=https://your-dokploy-server.com/api \
  -e DOKPLOY_API_KEY=your_token_here \
  dokploy-mcp

Run in HTTP Mode (Optional)

For web applications and HTTP-based integrations:

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

The server will be available at http://localhost:8080/mcp

MCP Client Configuration with Docker

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: Start the HTTP server first, then configure your client to connect to http://localhost:3000/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

Windows Installation

The configuration on Windows requires using 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

string

required

Your Dokploy server API URL. Must include the /api path.Example: https://dokploy.yourdomain.com/api

DOKPLOY_API_KEY

string

required

Your Dokploy API authentication token. Generate this from your Dokploy dashboard under Settings → API Keys.

MCP_TRANSPORT

string

default:"stdio"

Transport mode for the MCP server. Set to http or sse to enable HTTP mode.Options: stdio (default), http, sse

EXTERNAL_PORT

number

default:"3000"

External port for HTTP mode. Only used when MCP_TRANSPORT=http.

Troubleshooting

MCP client shows connection errors

Try adding @latest to the package name: @ahdev/dokploy-mcp@latest
Verify you’re using Node.js v18 or higher: node --version
Check your environment variables are correctly set in the config file
Ensure your Dokploy server is accessible from your machine

Authentication failed / 401 errors

Verify your DOKPLOY_API_KEY is correct
Check that the API key hasn’t expired in your Dokploy dashboard
Ensure your DOKPLOY_URL ends with /api (e.g., https://dokploy.yourdomain.com/api)

Tools not showing in MCP client

Restart your MCP client after adding the configuration
Check the MCP client logs for error messages
Try running the server manually to test: npx @ahdev/dokploy-mcp

npx command not found

Install Node.js v18 or higher from nodejs.org
Verify installation with: npx --version
On Windows, you may need to restart your terminal after installing Node.js

Docker container exits immediately

Check Docker logs: docker logs <container-id>
Verify environment variables are set correctly
Ensure the Dokploy server is reachable from within the Docker network

If you continue to experience issues, try running the MCP Inspector to debug:

npx -y @modelcontextprotocol/inspector npx @ahdev/dokploy-mcp

Next Steps

Now that you’ve installed Dokploy MCP Server, let’s verify it’s working and deploy your first application:

Quickstart Guide

Get started with your first deployment in minutes

Get Started

Configuration

Guides

Prerequisites

Installation by Client

Install in Cursor

Install in VS Code

Install in Windsurf

Install in Zed

Install in Claude Desktop

Install in BoltAI

Docker Installation

MCP Client Configuration with Docker

Windows Installation

Environment Variables

Troubleshooting

Next Steps

Quickstart Guide

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

​Prerequisites

​Installation by Client

​Install in Cursor

​Install in VS Code

​Install in Windsurf

​Install in Zed

​Install in Claude Desktop

​Install in BoltAI

​Docker Installation

​MCP Client Configuration with Docker

​Windows Installation

​Environment Variables

​Troubleshooting

​Next Steps

Quickstart Guide

Build docs developers (and LLMs) love

Prerequisites

Installation by Client

Install in Cursor

Install in VS Code

Install in Windsurf

Install in Zed

Install in Claude Desktop

Install in BoltAI

Docker Installation

MCP Client Configuration with Docker

Windows Installation

Environment Variables

Troubleshooting

Next Steps