MCP server for Cloudron instance management - list apps, get status, and manage your self-hosted applications
npm install @halecraft/mcp-cloudron


MCP server for Cloudron instance management. Manage apps, backups, users, and more through the Model Context Protocol.
- App Management - List, install, uninstall, start, stop, restart, clone, repair, update, and backup applications
- Backup Operations - List and create instance backups
- User Management - List, create, update, and delete users with role assignment
- Group Management - List and create groups for access control
- System Monitoring - Check instance status, storage, services, and platform updates
- Pre-flight Safety - Validation checks before destructive operations
- Async Task Tracking - Monitor and cancel long-running operations
- Packaging Guide - Interactive documentation for creating Cloudron packages
``bash`
npm install @halecraft/mcp-cloudron
Or run directly with npx:
`bash`
npx @halecraft/mcp-cloudron
| Variable | Required | Description |
| -------------------- | -------- | ----------------------------------------------------------- |
| CLOUDRON_BASE_URL | Yes | Your Cloudron instance URL (e.g., https://my.cloudron.io) |CLOUDRON_API_TOKEN
| | Yes | API token from Cloudron Admin Panel |
1. Log in to your Cloudron Admin Panel
2. Go to Settings → API Tokens
3. Click Create API Token
4. Give it a name (e.g., "MCP Server")
5. Select Read and Write permissions
6. Copy the generated token
Add to your Claude Desktop configuration (claude_desktop_config.json):
`json`
{
"mcpServers": {
"cloudron": {
"command": "npx",
"args": ["-y", "@halecraft/mcp-cloudron"],
"env": {
"CLOUDRON_BASE_URL": "https://your-cloudron-instance.com",
"CLOUDRON_API_TOKEN": "your-api-token"
}
}
}
}
| Tool | Description |
|------|-------------|
| cloudron_list_apps | List all installed applications with status and health |cloudron_get_app
| | Get detailed information about a specific application |cloudron_control_app
| | Start, stop, or restart an application |cloudron_configure_app
| | Update environment variables, memory limits, access control |cloudron_install_app
| | Install an application from the App Store |cloudron_uninstall_app
| | Uninstall an application (with pre-flight validation) |cloudron_clone_app
| | Clone an application to a new location |cloudron_repair_app
| | Repair a broken application |cloudron_update_app
| | Update an application to a newer version |cloudron_restore_app
| | Restore an application from a backup |cloudron_backup_app
| | Create a backup of a specific application |
| Tool | Description |
|------|-------------|
| cloudron_search_apps | Search the Cloudron App Store |cloudron_validate_manifest
| | Validate an app before installation |
| Tool | Description |
|------|-------------|
| cloudron_list_backups | List all available backups |cloudron_create_backup
| | Create a new instance backup |
| Tool | Description |
|------|-------------|
| cloudron_list_users | List all users |cloudron_get_user
| | Get details for a specific user |cloudron_create_user
| | Create a new user with role assignment |cloudron_update_user
| | Update user properties (email, role, password) |cloudron_delete_user
| | Delete a user (with pre-flight validation) |
| Tool | Description |
|------|-------------|
| cloudron_list_groups | List all groups |cloudron_create_group
| | Create a new group |
| Tool | Description |
|------|-------------|
| cloudron_get_status | Get Cloudron instance status and version |cloudron_check_storage
| | Check available disk space |cloudron_list_services
| | List platform services (MySQL, PostgreSQL, etc.) |cloudron_list_domains
| | List configured domains |cloudron_get_logs
| | Retrieve application or service logs |
| Tool | Description |
|------|-------------|
| cloudron_task_status | Check status of an async operation |cloudron_cancel_task
| | Cancel a running operation |cloudron_validate_operation
| | Pre-flight validation for destructive operations |
| Tool | Description |
|------|-------------|
| cloudron_check_updates | Check for Cloudron platform updates |cloudron_apply_update
| | Apply a platform update |
| Tool | Description |
|------|-------------|
| cloudron_packaging_guide | Get interactive guidance for creating Cloudron packages |cloudron_scaffold_package
| | Generate a complete package scaffold with all required files |cloudron_validate_package
| | Validate package files for errors and best practices |
#### Packaging Guide Topics
- overview - Quick start checklist and workflowmanifest
- - CloudronManifest.json field reference with examplesdockerfile
- - Dockerfile best practices and base image usageaddons
- - Available platform services (databases, auth, email, caching)testing
- - Integration test structure and patternspublishing
- - App Store submission process
#### Scaffold Package Options
Generate ready-to-use package files customized for your application:
| Parameter | Required | Description |
|-----------|----------|-------------|
| appType | Yes | Application type: nodejs, php, python, java, go, static |appName
| | Yes | Name of your application |appId
| | No | Reverse domain ID (e.g., com.example.myapp) |version
| | No | Initial version (default: 1.0.0) |httpPort
| | No | HTTP port (default: 8000) |healthCheckPath
| | No | Health check path (default: /) |addons
| | No | Required addons: localstorage, mysql, postgresql, mongodb, redis, ldap, oidc, sendmail, recvmail, scheduler |authMethod
| | No | Authentication: ldap, oidc, proxyAuth, none |memoryLimit
| | No | Memory limit in bytes |
#### Validate Package
Check your package files for errors and best practices:
| Parameter | Required | Description |
|-----------|----------|-------------|
| manifest | No | CloudronManifest.json content |dockerfile
| | No | Dockerfile content |startScript
| | No | start.sh content |
At least one file must be provided. Returns detailed validation report with errors, warnings, and suggestions.
| Resource URI | Description |
|--------------|-------------|
| cloudron://packaging-guide | Complete Cloudron packaging documentation with reference implementation |
Once configured, you can ask Claude to manage your Cloudron instance:
Instance Management:
- "List all my Cloudron apps"
- "What's the status of my Cloudron instance?"
- "Install Nextcloud on cloud.mydomain.com"
- "Create a backup of my instance"
- "Show me the logs for my WordPress app"
- "Create a new admin user with email admin@example.com"
Package Development:
- "Help me create a Cloudron package for my Node.js app"
- "Generate a scaffold for a Python app with PostgreSQL and Redis"
- "Scaffold a PHP app with OIDC authentication"
- "Validate my CloudronManifest.json file"
- "Check my Dockerfile for Cloudron best practices"
- "Show me how to configure addons in CloudronManifest.json"
- "What's the best practice for Dockerfile in Cloudron packages?"
`bash`
git clone https://github.com/halecraft/mcp-cloudron.git
cd mcp-cloudron
pnpm install
`bash`
pnpm build
`bash`
export CLOUDRON_BASE_URL="https://your-instance.com"
export CLOUDRON_API_TOKEN="your-token"
pnpm start
`bash`
pnpm test # Unit tests
pnpm test:integration # Integration tests (requires real Cloudron)
pnpm verify # All checks (format, tests, types)
This server wraps the Cloudron REST API. See TECHNICAL.md for detailed architecture documentation and API coverage analysis.
- cloudron_configure_app - May return 404 on some Cloudron versionscloudron_get_logs` - Returns raw text format
-
- Pagination not exposed for list operations
- 💬 Cloudron Forum - Discussion and support
- 🐛 Issue Tracker - Report bugs
- 💡 Feature Requests - Suggest improvements
- Model Context Protocol - MCP documentation
- Cloudron - Self-hosted app platform
- MCP TypeScript SDK
MIT - See LICENSE for details.
Contributions welcome! Please open an issue or submit a pull request.