@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?

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

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

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:

Tool Categories

The tools are organized by Dokploy's API structure:

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