Dokploy MCP Server

MCP server that provides 100% coverage of the Dokploy API — 463 tools auto-generated from the Dokploy OpenAPI specification. Manage projects, applications, databases, Docker Compose stacks, and more directly from Claude.

Requirements

• Node.js 18+ (check with node -v)
• A Dokploy account with API access
• API key from Settings → API Keys in your Dokploy dashboard

Quick Start

1. Install

npm install -g @jarciahdz111/dokploy-mcp

Or run without installing:

npx @jarciahdz111/dokploy-mcp

2. Configure Claude Desktop

Create or edit your Claude Desktop config file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "dokploy": {
      "command": "dokploy-mcp",
      "env": {
        "DOKPLOY_URL": "https://your-dokploy.com/api",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}

3. Configure Claude Code CLI (optional)

If you use the Claude Code CLI, add this to ~/.claude.json:

{
  "mcpServers": {
    "dokploy": {
      "command": "dokploy-mcp",
      "env": {
        "DOKPLOY_URL": "https://your-dokploy.com/api",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}

4. Restart Claude

Restart Claude Desktop or your terminal. The 463 Dokploy tools will be available.

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | DOKPLOY_URL | Your Dokploy API URL (e.g., https://cloud.dokploy.com/api) | Yes | — | | DOKPLOY_API_KEY | API key from Dokploy Settings → API Keys | Yes | — | | REQUEST_TIMEOUT_MS | HTTP request timeout in milliseconds | No | 30000 | | DEBUG | Set to 1 to enable debug logging (JSON to stderr) | No | — |

Available Tools

463 tools across 42 categories. Tool names follow the pattern dokploy_{category}_{action}.

| Category | Tools | Description | |----------|-------|-------------| | admin | 1 | Admin operations | | ai | 9 | AI-powered features | | application | 29 | Application deployment and management | | auditLog | 1 | Audit log access | | backup | 11 | Backup configuration and execution | | bitbucket | 7 | Bitbucket integration | | certificate | 4 | SSL certificate management | | cluster | 4 | Cluster management | | compose | 28 | Docker Compose stack operations | | customRole | 6 | Custom role permissions | | deployment | 8 | Deployment operations | | destination | 6 | Deployment destinations | | docker | 7 | Container and image management | | domain | 9 | Domain management | | environment | 7 | Environment variables | | gitea | 8 | Gitea integration | | gitProvider | 2 | Generic Git provider | | github | 6 | GitHub integration | | gitlab | 7 | GitLab integration | | licenseKey | 6 | License management | | mariadb | 14 | MariaDB database management | | mongo | 14 | MongoDB database management | | mounts | 6 | Volume mounts | | mysql | 14 | MySQL database management | | notification | 38 | Slack, email, Discord notifications | | organization | 11 | Organization management | | patch | 12 | Patch management | | port | 4 | Port configuration | | postgres | 14 | PostgreSQL database management | | previewDeployment | 4 | Preview deployments | | project | 8 | Project and environment management | | redis | 14 | Redis cache management | | redirects | 4 | Redirect rules | | registry | 7 | Docker registry management | | rollback | 2 | Deployment rollback | | schedule | 6 | Scheduled tasks | | security | 4 | Security settings | | server | 16 | Server provisioning and management | | settings | 49 | Server and application settings | | sso | 10 | SSO/OIDC/SAML configuration | | sshKey | 6 | SSH key management | | stripe | 7 | Stripe billing | | swarm | 3 | Docker Swarm mode | | user | 20 | User and session management | | volumeBackups | 6 | Volume backup management | | whitelabeling | 4 | Whitelabel configuration |

Usage Examples

List all projects

dokploy_project_all

Get Docker containers

dokploy_docker_getContainers

Get application details

dokploy_application_one
// arguments: { applicationId: "your-application-id" }

Deploy an application

dokploy_application_deploy
// arguments: { applicationId: "your-application-id", to: "production" }

List PostgreSQL databases

dokploy_postgres_all

Get server status

dokploy_settings_getDokployVersion

Restart a Docker container

dokploy_docker_restartContainer
// arguments: { containerId: "your-container-id" }

Local Development

# Clone the repository
git clone https://github.com/jarciahdz111/dokploy-mcp.git
cd dokploy-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Test
node test-mcp.js

Troubleshooting

"Unauthorized" Error

Your DOKPLOY_API_KEY is invalid or expired.

1. Go to Settings → API Keys in your Dokploy dashboard
2. Generate a new API key
3. Update the DOKPLOY_API_KEY in your Claude Desktop config
4. Restart Claude

"Connection Refused" Error

The server cannot reach your Dokploy instance.

1. Verify DOKPLOY_URL is correct (must include /api at the end)
2. Check your Dokploy server is running and accessible
3. If behind a corporate firewall, set proxy environment variables:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Request Timeout Error

The request took too long and was aborted.

Increase the timeout by setting REQUEST_TIMEOUT_MS:

{
  "mcpServers": {
    "dokploy": {
      "env": {
        "DOKPLOY_URL": "https://your-dokploy.com/api",
        "DOKPLOY_API_KEY": "your-api-key",
        "REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

Enable Debug Logging

To see detailed request/response logs:

{
  "mcpServers": {
    "dokploy": {
      "env": {
        "DOKPLOY_URL": "https://your-dokploy.com/api",
        "DOKPLOY_API_KEY": "your-api-key",
        "DEBUG": "1"
      }
    }
  }
}

Debug output is written to stderr as JSON.

How It Works

This MCP server is auto-generated from the Dokploy OpenAPI specification. When Dokploy releases an API update, a new version of this package can be published with updated tool coverage — no manual tool writing required.

The server:

1. Loads the embedded OpenAPI spec (1.4 MB, 463 endpoints)
2. Converts each endpoint to an MCP tool with Zod-validated input schema
3. Routes GET requests as tRPC queries and POST requests as tRPC mutations
4. Handles tRPC response wrapping and error parsing automatically

API Coverage

• 100% of Dokploy API v0.28.8 endpoints
• 463 MCP tools
• 42 functional categories
• Auto-generated and auto-synced with API spec

Contributing

Want to modify or extend this MCP server? See CLAUDE.md for the development workflow, architecture overview, and contribution guidelines.

License

MIT