mcp-cloudron
MCP server for Cloudron instance management. List apps, get status, and manage your self-hosted applications through the Model Context Protocol.
Features
- List Applications: Get all installed apps with status, health, and memory usage
- Get App Details: Retrieve detailed information about specific applications
- Instance Status: Check Cloudron version, provider, and configuration
Installation
npm install @serenichron/mcp-cloudron
Or run directly with npx:
npx @serenichron/mcp-cloudron
Configuration
Environment Variables
| 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 |
Getting an API Token
- Log in to your Cloudron Admin Panel
- Go to Settings → API Tokens
- Click Create API Token
- Give it a name (e.g., "MCP Server")
- Copy the generated token
Usage with Claude Desktop
Add to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"cloudron": {
"command": "npx",
"args": ["@serenichron/mcp-cloudron"],
"env": {
"CLOUDRON_BASE_URL": "https://your-cloudron-instance.com",
"CLOUDRON_API_TOKEN": "your-api-token"
}
}
}
}
Usage with Docker MCP Gateway
Add to your Docker MCP config (~/.docker/mcp/config.yaml):
mcpServers:
cloudron:
command: npx
args: ["@serenichron/mcp-cloudron"]
env:
CLOUDRON_BASE_URL: "https://your-cloudron-instance.com"
CLOUDRON_API_TOKEN: "your-api-token"
Available Tools
cloudron_list_apps
List all installed applications on the Cloudron instance.
Parameters: None
Returns: List of apps with name, domain, ID, state, health, and memory usage.
Example output:
Found 3 apps:
WordPress (blog.example.com)
ID: abc123-def456
State: installed
Health: healthy
Memory: 512 MB
GitLab (git.example.com)
ID: xyz789-uvw012
State: installed
Health: healthy
Memory: 4096 MB
cloudron_get_app
Get detailed information about a specific application.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
appId | string | Yes | The unique identifier of the application |
Returns: App details including name, domain, state, health, and memory.
cloudron_get_status
Get the current status and configuration of the Cloudron instance.
Parameters: None
Returns: Instance information including name, version, admin URL, provider, and demo mode status.
Example output:
Cloudron Status:
Name: My Cloudron
Version: 9.0.13
Admin URL: my.cloudron.io
Provider: digitalocean
Demo Mode: false
Development
Setup
git clone https://github.com/serenichron/mcp-cloudron.git
cd mcp-cloudron
npm install
Build
npm run build
Run locally
export CLOUDRON_BASE_URL="https://your-instance.com"
export CLOUDRON_API_TOKEN="your-token"
npm start
Test
npm test
API Reference
The server uses the Cloudron REST API. Currently implemented endpoints:
GET /api/v1/apps- List all applicationsGET /api/v1/apps/:id- Get application by IDGET /api/v1/cloudron/status- Get instance status
Changelog
v0.2.0 (2025-12-26)
New Features:
- 15 new MCP tools across app management, backups, users, infrastructure
- Pre-flight validation for destructive operations (F37)
- Storage checks before data creation (F36)
- Async task tracking and cancellation (F34, F35)
Critical Bug Fixes:
- F23b: Corrected endpoint path and added required domain parameter
- F04: Fixed HTTP method (DELETE → POST) for uninstall operation
- Both bugs discovered via real API testing (mock tests validated nothing)
Testing:
- Real Cloudron API integration testing
- Validated against live instance
- All 16 tools tested with actual API calls
Roadmap
Future versions may include:
- Domain configuration
- App installation from App Store
Community
- 💬 Cloudron Forum - Discussion and support
- 🐛 Issue Tracker - Report bugs
- 💡 Feature Requests - Suggest improvements
Related Projects
- Model Context Protocol - MCP documentation
- Cloudron - Self-hosted app platform
License
MIT - See LICENSE for details.
Contributing
Contributions welcome! Please open an issue or submit a pull request.