Dokploy MCP Server

<div align="center">

A powerful MCP server for managing Dokploy deployments

Features • Installation • Usage • API Reference • Contributing

</div>

---

🚀 Overview

Dokploy MCP Server is a comprehensive Model Context Protocol (MCP) server that provides seamless integration with Dokploy - the open-source alternative to Netlify, Vercel, and Heroku. This server enables AI assistants and applications to interact with Dokploy's powerful deployment platform through a standardized interface.

What is Dokploy?

Dokploy is a free, self-hostable Platform as a Service (PaaS) that simplifies application deployment and management. It provides:

• Docker-based deployments
• Support for multiple frameworks and languages
• Automatic SSL certificates
• Database management
• Domain configuration
• And much more!

✨ Features

🗂️ Project Management

• Create, list, and delete projects
• Organize applications by project
• Manage project-level configurations

📦 Application Deployment

• Deploy applications from Git repositories (GitHub, GitLab, etc.)
• Support for Docker and Docker Compose
• Start, stop, and restart applications
• Real-time deployment status
• Update environment variables
• Application monitoring and health checks

🗄️ Database Management

• Support for multiple database types:
  • PostgreSQL
  • MySQL
  • MongoDB
  • Redis
  • MariaDB
• Create and manage databases
• Connection string management

🌐 Domain & SSL Management

• Add custom domains to applications
• Automatic SSL certificate provisioning via Let's Encrypt
• Domain verification and configuration

💾 Backup & Restore

• Create manual and scheduled backups
• List available backups
• Restore databases from backups
• Disaster recovery support

📊 Monitoring & Logs

• Real-time application logs
• Application status monitoring
• Performance metrics
• Error tracking

📚 Documentation Resources

• Built-in documentation access
• Quick start guides
• API reference
• Best practices

🤖 Interactive Prompts

• Guided deployment workflows
• Database setup assistance
• Troubleshooting helpers

📋 Prerequisites

• Dokploy Instance: A running Dokploy instance (self-hosted or cloud)
• API Token: Authentication token from your Dokploy dashboard
• Node.js: Version 18 or higher
• Bun (optional): For faster package management

🔧 Installation

Quick Start with Smithery

# Install via Smithery
npx create-smithery dokploy-mcp
cd dokploy-mcp

Manual Installation

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

# Install dependencies (with bun)
bun install

# Or with npm
npm install

⚙️ Configuration

Create a configuration file or set environment variables:

# smithery.yaml
dokployUrl: "https://dok.bish.one"  # Your Dokploy instance URL
apiToken: "your-api-token-here"     # Your Dokploy API token
debug: false                         # Enable debug logging

Getting Your API Token

1. Log in to your Dokploy dashboard
2. Navigate to Settings → API Tokens
3. Generate a new token
4. Copy and save it securely

🚦 Usage

Starting the Server

# Development mode
bun run dev

# Or with npm
npm run dev

The server will start on http://localhost:3000 by default.

Example Operations

Deploy an Application

// 1. Create a project
await createProject({
  name: "my-awesome-project",
  description: "My first Dokploy project"
})

// 2. Create an application
await createApplication({
  projectId: "project-id",
  name: "my-app",
  appType: "github",
  repository: "https://github.com/username/repo",
  branch: "main"
})

// 3. Deploy the application
await deployApplication({
  applicationId: "app-id"
})

Manage Databases

// Create a PostgreSQL database
await createDatabase({
  projectId: "project-id",
  name: "my-database",
  type: "postgres",
  username: "admin",
  password: "secure-password"
})

// Create a backup
await createBackup({
  databaseId: "database-id"
})

Monitor Applications

// Get application status
await getApplicationStatus({
  applicationId: "app-id"
})

// View recent logs
await getLogs({
  applicationId: "app-id",
  lines: 100
})

📖 API Reference

Tools

Project Management

Tool	Description	Parameters
list-projects	List all projects	None
create-project	Create a new project	name, description
delete-project	Delete a project	projectId

Application Management

Tool	Description	Parameters
list-applications	List all applications	projectId
create-application	Create a new application	projectId, name, appType, repository, etc.
deploy-application	Deploy an application	applicationId
start-application	Start an application	applicationId
stop-application	Stop an application	applicationId
restart-application	Restart an application	applicationId
delete-application	Delete an application	applicationId
get-logs	Get application logs	applicationId, lines
get-application-status	Get application status	applicationId
update-env-vars	Update environment variables	applicationId, env

Database Management

Tool	Description	Parameters
create-database	Create a new database	projectId, name, type, etc.
list-databases	List all databases	projectId

Domain Management

Tool	Description	Parameters
add-domain	Add a custom domain	applicationId, domain, enableSSL
list-domains	List all domains	applicationId

Backup & Restore

Tool	Description	Parameters
create-backup	Create a database backup	databaseId
list-backups	List all backups	databaseId
restore-backup	Restore from backup	backupId

Resources

• dokploy://docs - Complete Dokploy documentation
• dokploy://quickstart - Quick start guide
• dokploy://api-reference - API reference

Prompts

• deploy-app - Guided application deployment
• setup-database - Guided database setup
• troubleshoot - Application troubleshooting assistant

🔐 Security

• API Token: Store your API token securely. Never commit it to version control.
• HTTPS: Always use HTTPS for production deployments
• Environment Variables: Use environment variables for sensitive data
• Access Control: Configure proper access controls in your Dokploy instance

🛠️ Development

Project Structure

dokploy-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── package.json          # Project dependencies
├── smithery.yaml         # Runtime configuration
├── README.md            # This file
└── .gitignore           # Git ignore rules

Building for Production

# Build the server
bun run build

# Or with npm
npm run build

Testing

# Run the development server
bun run dev

# Test with curl
curl -X POST "http://127.0.0.1:3000/mcp?dokployUrl=https://dok.bish.one&apiToken=your-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

🚢 Deployment

Deploy to Smithery

1. Push your code to GitHub
2. Visit smithery.ai/new
3. Connect your repository
4. Configure your Dokploy credentials
5. Deploy!

Deploy to Your Own Infrastructure

# Build the project
bun run build

# Run the server
PORT=3000 node dist/index.js

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Dokploy - The amazing PaaS platform
• Smithery - MCP server hosting and registry
• Model Context Protocol - The protocol that makes this possible
• Anthropic - For creating the MCP standard

📞 Support

• Documentation: docs.dokploy.com
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Dokploy Discord: Join the Dokploy community
• Smithery Discord: discord.gg/Afd38S5p9A

🗺️ Roadmap

• [ ] Add support for Docker Compose deployments
• [ ] Implement real-time deployment progress tracking
• [ ] Add metrics and analytics integration
• [ ] Support for custom build scripts
• [ ] Multi-region deployment support
• [ ] Advanced monitoring and alerting
• [ ] Integration with CI/CD pipelines
• [ ] Webhook support for automated deployments

📊 Stats

---

<div align="center">

Made with ❤️ by the Dokploy community

⬆ back to top

</div>