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

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

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 applications
• GET /api/v1/apps/:id - Get application by ID
• GET /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.

Related

• Cloudron Documentation
• Model Context Protocol
• MCP TypeScript SDK