MCP server for Cloudron instance management - list apps, get status, and manage your self-hosted applications
npm install @serenichron/mcp-cloudron
MCP server for Cloudron instance management. List apps, get status, and manage your self-hosted applications through the Model Context Protocol.
- 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
``bash`
npm install @serenichron/mcp-cloudron
Or run directly with npx:
`bash`
npx @serenichron/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. Copy the generated token
Add to your Claude Desktop configuration (claude_desktop_config.json):
`json`
{
"mcpServers": {
"cloudron": {
"command": "npx",
"args": ["@serenichron/mcp-cloudron"],
"env": {
"CLOUDRON_BASE_URL": "https://your-cloudron-instance.com",
"CLOUDRON_API_TOKEN": "your-api-token"
}
}
}
}
Add to your Docker MCP config (~/.docker/mcp/config.yaml):
`yaml`
mcpServers:
cloudron:
command: npx
args: ["@serenichron/mcp-cloudron"]
env:
CLOUDRON_BASE_URL: "https://your-cloudron-instance.com"
CLOUDRON_API_TOKEN: "your-api-token"
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
`
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.
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
`bash`
git clone https://github.com/serenichron/mcp-cloudron.git
cd mcp-cloudron
npm install
`bash`
npm run build
`bash`
export CLOUDRON_BASE_URL="https://your-instance.com"
export CLOUDRON_API_TOKEN="your-token"
npm start
`bash`
npm test
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
-
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
Future versions may include:
- [ ] Domain configuration
- [ ] App installation from App Store
- 💬 Cloudron Forum - Discussion and support
- 🐛 Issue Tracker - Report bugs
- 💡 Feature Requests - Suggest improvements
- Model Context Protocol - MCP documentation
- Cloudron - Self-hosted app platform
MIT - See LICENSE for details.
Contributions welcome! Please open an issue or submit a pull request.
- Cloudron Documentation
- Model Context Protocol
- MCP TypeScript SDK