MCP clients - Dokploy MCP Server

The Dokploy MCP Server works with various MCP-compatible clients. This guide provides complete configuration instructions for each supported client.

Supported Clients

The Dokploy MCP Server supports the following MCP clients:

Cursor - AI-powered code editor
VS Code - Visual Studio Code with MCP extension
Windsurf - AI development environment
Zed - High-performance code editor
Claude Desktop - Anthropic’s desktop application
BoltAI - AI assistant for macOS

Configuration by Client

Cursor

Cursor is an AI-powered code editor with built-in MCP support.

Configuration Location

Global: ~/.cursor/mcp.json (applies to all projects)
Project: .cursor/mcp.json (applies to current project only)

Configuration

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

Bun
Deno
Docker

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

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

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

How to Configure

Open Cursor
Go to Settings → Cursor Settings → MCP
Click Add new global MCP server
Paste the configuration above
Save the file
Restart Cursor

You can also install per-project by creating .cursor/mcp.json in your project root.

Verification

After configuration:

Open the Cursor composer
Type @ to see available MCP servers
You should see “dokploy-mcp” in the list
Test by asking: “List all my Dokploy projects”

Documentation

Cursor MCP Documentation

VS Code

Visual Studio Code supports MCP through the official extension.

Installation

Install VS Code Insiders (required for MCP support)
Click one of these buttons to auto-install:
- Install in VS Code (npx)
- Install in VS Code Insiders (npx)

Configuration Location

The VS Code MCP configuration file location varies by operating system:

macOS: ~/Library/Application Support/Code - Insiders/User/globalStorage/github.vscode-mcp/settings.json
Windows: %APPDATA%\Code - Insiders\User\globalStorage\github.vscode-mcp\settings.json
Linux: ~/.config/Code - Insiders/User/globalStorage/github.vscode-mcp/settings.json

Configuration

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

VS Code uses a different configuration format with "servers" instead of "mcpServers" and requires "type": "stdio".

How to Configure

Open VS Code Insiders
Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type “MCP: Edit Settings”
Paste the configuration above
Save the file
Reload the window

Verification

After configuration:

Open GitHub Copilot Chat
The MCP server should be available automatically
Test by asking: “List all my Dokploy projects”

Documentation

VS Code MCP Documentation

Windsurf

Windsurf is an AI-powered development environment with built-in MCP support.

Configuration Location

The Windsurf MCP configuration file location varies by operating system:

macOS: ~/Library/Application Support/Windsurf/mcp_config.json
Windows: %APPDATA%\Windsurf\mcp_config.json
Linux: ~/.config/Windsurf/mcp_config.json

Configuration

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

How to Configure

Open Windsurf
Navigate to settings
Find the MCP configuration section
Paste the configuration above
Save and restart Windsurf

Verification

After configuration:

Open the Windsurf AI panel
The Dokploy MCP server should be loaded
Test by asking: “Show me my Dokploy applications”

Documentation

Windsurf MCP Documentation

Zed

Zed is a high-performance code editor with context server support (MCP).

Configuration Location

macOS/Linux: ~/.config/zed/settings.json
Windows: %APPDATA%\Zed\settings.json

Configuration

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

Zed uses "context_servers" and has a different configuration structure with "command" as an object and "settings" for environment variables.

How to Configure

Open Zed
Press Cmd+, (Mac) or Ctrl+, (Windows/Linux) to open settings
Add the configuration above to your settings.json
Save the file
Restart Zed

Verification

After configuration:

Open the Zed assistant
The Dokploy context server should be available
Test by asking: “List my Dokploy projects”

Documentation

Zed Context Servers Documentation

Claude Desktop

Claude Desktop is Anthropic’s official desktop application with native MCP support.

Configuration Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Configuration

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

How to Configure

Close Claude Desktop if it’s running
Open the configuration file in your text editor
Paste the configuration above
Save the file
Start Claude Desktop

Make sure Claude Desktop is fully closed before editing the configuration file. Changes won’t be picked up if the app is running.

Verification

After configuration:

Open Claude Desktop
Look for a hammer icon indicating MCP tools are available
Test by asking: “Can you list my Dokploy projects?”
Claude should use the MCP tools to fetch and display your projects

Documentation

BoltAI

BoltAI is an AI assistant for macOS with MCP support.

Configuration Location

BoltAI configuration is managed through the app’s settings interface.

Configuration

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

How to Configure

Open BoltAI
Go to Settings
Navigate to Plugins section
Paste the JSON configuration above
Save the settings
Restart BoltAI

Verification

After configuration:

Open BoltAI
Start a new conversation
Test by asking: “Show me my Dokploy projects”

Documentation

Check BoltAI’s official documentation for the latest MCP configuration details

Windows Configuration

Windows requires a slightly different configuration format. 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"
      }
    }
  }
}

Windows users must use cmd with /c flag, not just npx directly.

Common Configuration Patterns

Project-Specific Configuration

For project-specific configuration (Cursor only):

// .cursor/mcp.json in your project root
{
  "mcpServers": {
    "dokploy-mcp": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://your-project-dokploy.com/api",
        "DOKPLOY_API_KEY": "project-specific-token"
      }
    }
  }
}

Multiple Dokploy Instances

You can configure multiple Dokploy instances:

{
  "mcpServers": {
    "dokploy-production": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://prod.dokploy.com/api",
        "DOKPLOY_API_KEY": "prod-token"
      }
    },
    "dokploy-staging": {
      "command": "npx",
      "args": ["-y", "@ahdev/dokploy-mcp"],
      "env": {
        "DOKPLOY_URL": "https://staging.dokploy.com/api",
        "DOKPLOY_API_KEY": "staging-token"
      }
    }
  }
}

Local Development Build

For testing local development builds:

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

Troubleshooting

Server not showing up in client

Verify the configuration file is in the correct location
Check that the JSON syntax is valid (no trailing commas)
Ensure environment variables are set correctly
Restart the MCP client completely
Check client logs for error messages

Authentication errors

Verify DOKPLOY_URL includes /api suffix
Confirm DOKPLOY_API_KEY is valid and not expired

Test the connection manually:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-dokploy-server.com/api/health

Check that your Dokploy server is accessible

Tools not working

Check that Node.js v18+ is installed: node --version
Verify npx is available: npx --version

Try running the server manually:

DOKPLOY_URL=https://your-server.com/api \
DOKPLOY_API_KEY=your-token \
npx -y @ahdev/dokploy-mcp

Look for error messages in the client’s developer console

Windows-specific issues

Make sure you’re using the Windows configuration format with cmd
Check that Node.js is in your PATH: where node

Try using full path to npx:

{
  "command": "cmd",
  "args": ["/c", "C:\\Program Files\\nodejs\\npx", "-y", "@ahdev/dokploy-mcp"]
}

Verify Windows firewall isn’t blocking Node.js

Configuration file not found

If you can’t find the configuration file:

Create the parent directory if it doesn’t exist:

# macOS/Linux
mkdir -p ~/.cursor

# Windows
mkdir %APPDATA%\Cursor

Create the configuration file:

# macOS/Linux
touch ~/.cursor/mcp.json

# Windows
type nul > %APPDATA%\Cursor\mcp.json

Add your configuration and save

Server keeps restarting

If the server keeps restarting or crashing:

Check for conflicting MCP servers with the same name
Verify all dependencies are installed correctly

Try clearing the package cache:

npx clear-npx-cache
# or
rm -rf ~/.npm/_npx

Test with the @latest tag:

"args": ["-y", "@ahdev/dokploy-mcp@latest"]

Testing Your Configuration

Using MCP Inspector

The MCP Inspector is a useful tool for testing your configuration:

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

This will:

Start the Dokploy MCP server
Open a web interface for testing
Show all available tools and their schemas
Allow you to test tool calls interactively

Manual Testing

After configuration, test the connection:

# Set environment variables
export DOKPLOY_URL="https://your-dokploy-server.com/api"
export DOKPLOY_API_KEY="your-dokploy-api-token"

# Run the server
npx -y @ahdev/dokploy-mcp

If the server starts without errors, your configuration is correct.

Getting Help

If you encounter issues:

Check the GitHub Issues
Review the troubleshooting guide
Join the Dokploy community for support
Open a new issue with:
- Your client and version
- Operating system
- Configuration file contents (without sensitive data)
- Error messages from logs

Get Started

Configuration

Guides

​Supported Clients

​Configuration by Client

​Configuration Location

​Configuration

​Alternative Runtimes

​How to Configure

​Verification

​Documentation

​Installation

​Configuration Location

​Configuration

​How to Configure

​Verification

​Documentation

​Configuration Location

​Configuration

​How to Configure

​Verification

​Documentation

​Configuration Location

​Configuration

​How to Configure

​Verification

​Documentation

​Configuration Location

​Configuration

​How to Configure

​Verification

​Documentation

​Configuration Location

​Configuration

​How to Configure

​Verification

​Documentation

​Windows Configuration

​Common Configuration Patterns

​Project-Specific Configuration

​Multiple Dokploy Instances

​Local Development Build

​Troubleshooting

​Testing Your Configuration

​Using MCP Inspector

​Manual Testing

​Getting Help

​See Also

Build docs developers (and LLMs) love

Supported Clients

Configuration by Client

Configuration Location

Configuration

Alternative Runtimes

How to Configure

Verification

Documentation

Installation

Configuration Location

Configuration

How to Configure

Verification

Documentation

Configuration Location

Configuration

How to Configure

Verification

Documentation

Configuration Location

Configuration

How to Configure

Verification

Documentation

Configuration Location

Configuration

How to Configure

Verification

Documentation

Configuration Location

Configuration

How to Configure

Verification

Documentation

Windows Configuration

Common Configuration Patterns

Project-Specific Configuration

Multiple Dokploy Instances

Local Development Build

Troubleshooting

Testing Your Configuration

Using MCP Inspector

Manual Testing

Getting Help

See Also