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.

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

Build the Docker Image:

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

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

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

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:

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:

git clone https://github.com/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

Try adding @latest to the package name.
Make sure you are using Node v18 or higher to have native fetch support with npx.
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.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github		.github
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TOOLS.md		TOOLS.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

License

Uh oh!

Dokploy/mcp

Folders and files

Latest commit

History

Repository files navigation

Dokploy MCP Server

🛠️ Getting Started

Requirements

Install in Cursor

Install in Windsurf

Install in VS Code

Install in Zed

Install in Claude Desktop

Install in BoltAI

Using Docker

Install in Windows

Environment Variables

🚀 Transport Modes

Stdio Mode (Default)

HTTP Mode (Streamable HTTP + Legacy SSE)

📚 Available Tools

🗂️ Project Management (6 tools)

🚀 Application Management (26 tools)

🌐 Domain Management (9 tools)

🐘 PostgreSQL Database Management (13 tools)

🐬 MySQL Database Management (13 tools)

🏗️ Architecture

🔧 Development

Local Configuration Example

Testing with MCP Inspector

Documentation

🔧 Troubleshooting

MCP Client Errors

🤝 Contributing

🆘 Support

📄 License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

Packages