@sattva/dokploy-mcp

MCP server for Dokploy — dynamically generates 420+ tools from the Dokploy OpenAPI spec. Deploy, manage, and monitor your self-hosted infrastructure through AI assistants.

Why This Package?

Feature	@sattva/dokploy-mcp	Community alternatives
Auth method	x-api-key header (correct)	Often missing or incorrect
API coverage	420+ tools (full OpenAPI)	Manual subset (~30-50 tools)
Dependencies	2 (@modelcontextprotocol/sdk, zod)	Often pulls in OpenAI SDK, axios, etc.
Update strategy	Auto-generates from live spec	Manual maintenance required
Safety annotations	readOnlyHint / destructiveHint	Usually missing
Package size	~25 KB (dist only)	Varies

Key Features

• Dynamic OpenAPI discovery — fetches the spec from your Dokploy instance at startup, so new API endpoints are available immediately after a Dokploy upgrade
• 420+ tools — every Dokploy API endpoint becomes an MCP tool automatically
• Correct x-api-key authentication — uses the proper header that Dokploy expects
• Zod input validation — OpenAPI schemas are converted to Zod for runtime type checking
• Safety annotations — read-only operations are marked with readOnlyHint, destructive ones with destructiveHint
• Zero-config updates — upgrade Dokploy, restart the MCP server, get new tools
• Minimal dependencies — only @modelcontextprotocol/sdk and zod

Quick Start

Claude Code (CLI)

claude mcp add --transport stdio \
  --env DOKPLOY_URL=https://dokploy.example.com \
  --env DOKPLOY_API_KEY=your-api-key-here \
  dokploy -- npx -y @sattva/dokploy-mcp@latest

Manual configuration

Add the following to your MCP client config file:

{
  "mcpServers": {
    "dokploy": {
      "command": "npx",
      "args": ["-y", "@sattva/dokploy-mcp@latest"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Client	Config file
Claude Code	~/.claude/mcp.json
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json
Windsurf	~/.windsurf/mcp.json

Run directly from the command line

DOKPLOY_URL=https://dokploy.example.com \
DOKPLOY_API_KEY=your-api-key-here \
npx @sattva/dokploy-mcp@latest

Configuration

Variable	Required	Description
DOKPLOY_URL	Yes	Base URL of your Dokploy instance (e.g. https://dokploy.example.com). Do not append /api — the server adds it automatically.
DOKPLOY_API_KEY	Yes	API key for authentication

Getting Your API Key

1. Log in to your Dokploy dashboard
2. Go to Settings → Profile
3. Under API / Tokens, click Generate Token
4. Copy the generated key

Tool Naming Convention

OpenAPI paths are converted to tool names:

OpenAPI Path	Tool Name
/api/application.one	application_one
/api/project.all	project_all
/api/server.create	server_create
/api/docker.getContainers	docker_getContainers
/api/domain.update	domain_update

Tool Categories

The tools are organized by Dokploy's API structure:

Category	Examples	Description
Application	application_one, application_create, application_deploy	Manage applications
Project	project_all, project_create, project_one	Manage projects
Server	server_all, server_create, server_one	Manage servers
Docker	docker_getContainers, docker_getConfig	Docker operations
Domain	domain_create, domain_update, domain_all	Domain management
Deployment	deployment_all, deployment_allByApplication	Deployment history
Database	mysql_*, postgres_*, mariadb_*, mongo_*, redis_*	Database services
Compose	compose_*	Docker Compose services
Registry	registry_all, registry_create, registry_one	Container registries
Certificate	certificates_*	SSL certificates
User	user_all, user_one, user_update	User management
Settings	settings_*	Instance settings

Safety Annotations

Every tool is annotated based on its HTTP method and operation:

• readOnlyHint: true — GET requests (safe to call, no side effects)
• destructiveHint: true — operations that deploy, delete, stop, restart, or otherwise modify state

This helps AI assistants make safer decisions about which tools to call without confirmation.

Troubleshooting

DOKPLOY_URL must not end with /api

The MCP server appends /api to the base URL automatically. If you set DOKPLOY_URL=https://dokploy.example.com/api, requests will go to /api/api/... and fail.

Correct: https://dokploy.example.com Wrong: https://dokploy.example.com/api

Windows: npx does not pass environment variables

On Windows, npx launched via cmd /c may not forward env variables correctly. Use node with the full path to dist/index.js instead:

{
  "mcpServers": {
    "dokploy": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@sattva\\dokploy-mcp\\dist\\index.js"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key-here"
      }
    }
  }
}

To find the path after a global install:

npm install -g @sattva/dokploy-mcp
npm root -g
# → C:\Users\<you>\AppData\Roaming\npm\node_modules

Connection refused / timeout

• Verify DOKPLOY_URL is reachable: curl https://dokploy.example.com/api/settings.getOpenApiDocument -H "x-api-key: YOUR_KEY"
• Check that port 443 (or your custom port) is open
• Ensure the API key is valid and has not been revoked

0 tools registered

If the server starts but registers 0 tools, the OpenAPI spec may be empty or in an unexpected format. Check your Dokploy version — the OpenAPI endpoint was introduced in Dokploy v0.9+.

Development

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

Test locally

# Watch mode
npm run dev

# Point your MCP client to the local build:

{
  "mcpServers": {
    "dokploy": {
      "command": "node",
      "args": ["/path/to/dokploy-mcp/dist/index.js"],
      "env": {
        "DOKPLOY_URL": "https://dokploy.example.com",
        "DOKPLOY_API_KEY": "your-api-key"
      }
    }
  }
}

Architecture

┌────────────────┐     ┌──────────────┐     ┌──────────────────┐
│  MCP Client    │────▶│  MCP Server  │────▶│  Dokploy API     │
│  (Claude, etc) │◀────│  (this pkg)  │◀────│  (your instance) │
└────────────────┘     └──────────────┘     └──────────────────┘
       stdio            At startup:
                        1. Fetch OpenAPI spec
                        2. Parse paths → tools
                        3. Build Zod schemas
                        4. Register with MCP SDK

Pipeline:

1. Startup — reads DOKPLOY_URL and DOKPLOY_API_KEY from environment
2. Spec fetch — calls GET /api/settings.getOpenApiDocument on the Dokploy instance
3. Tool generation — iterates over every path+method in the OpenAPI spec, builds Zod input schemas from parameters and request bodies
4. Registration — registers each tool with the MCP SDK, including descriptions and safety annotations
5. Runtime — when a tool is called, the server makes the corresponding HTTP request to Dokploy with x-api-key auth and returns the JSON response

License

MIT — Copyright (c) 2025-2026 Sattva