Skip to main content
Glama
Sign In
mcp-cloudron

mcp-cloudron

by serenichron
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

mcp-cloudron

npm version License: MIT MCP

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

Related MCP server: MCP Beget

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

Related Projects

License

MIT - See LICENSE for details.

Contributing

Contributions welcome! Please open an issue or submit a pull request.

Related

Available Tools

19 tools
cloudron_cancel_taskA

Cancel a running async operation (kill switch). Returns updated task status with state "cancelled". Already completed tasks cannot be cancelled. Cancelled tasks cleanup resources (e.g., partial backups deleted).

Inputs: taskId (required).

cloudron_check_storageA

Check available disk space before operations that create data (backup, install). Returns available/total/used disk space in MB, plus warning and critical threshold alerts.

Inputs: requiredMB.

cloudron_configure_appB

Update application configuration including environment variables, memory limits, and access control settings. Returns 200 OK with updated app config and restart requirement flag.

Inputs: appId (required), config (required).

cloudron_control_appA

Control app lifecycle (start, stop, restart). Returns 202 Accepted with task ID for async operation tracking via cloudron_task_status.

Inputs: appId (required), action (required).

cloudron_create_backupA

Create a new backup of the Cloudron instance. Performs F36 pre-flight storage check (requires 5GB minimum). Returns task ID for tracking backup progress via cloudron_task_status (F34).

Inputs: no named parameters.

cloudron_create_userA

Create a new user on the Cloudron instance with role assignment (atomic operation). Password must be at least 8 characters long and contain at least 1 uppercase letter and 1 number. Returns 201 Created with user object.

Inputs: email (required), password (required), role (required).

cloudron_get_appC

Get detailed information about a specific application by its ID.

Inputs: appId (required).

cloudron_get_logsB

Get logs for an app or service. Logs are formatted with timestamps and severity levels for readability. Type parameter determines endpoint: "app" calls GET /api/v1/apps/:id/logs, "service" calls GET /api/v1/services/:id/logs.

Inputs: resourceId (required), type (required), lines.

cloudron_get_statusB

Get the current status and configuration of the Cloudron instance.

Inputs: no named parameters.

cloudron_install_appA

Install application from Cloudron App Store with pre-flight validation. Calls F23a (cloudron_validate_manifest) to verify app exists and F36 (cloudron_check_storage) to ensure sufficient disk space. Returns task ID for async operation tracking via cloudron_task_status.

Inputs: manifestId (required), location (required), domain (required), accessRestriction (required), +2 more.

cloudron_list_appsA

List all installed applications on the Cloudron instance. Returns app details including name, domain, status, and health.

Inputs: no named parameters.

cloudron_list_backupsA

List all backups available on the Cloudron instance. Returns backup details including ID, timestamp, size, app count, and status. Backups are sorted by timestamp (newest first).

Inputs: no named parameters.

cloudron_list_domainsA

List all configured domains on the Cloudron instance. Returns domain details including name, provider, verification status, and TLS configuration.

Inputs: no named parameters.

cloudron_list_usersA

List all users on the Cloudron instance. Returns user details including ID, email, username, role, and creation date. Users are sorted by role (admin, user, guest) then email.

Inputs: no named parameters.

cloudron_search_appsA

Search the Cloudron App Store for available applications. Returns app details including name, description, version, icon URL, and install count. Results are sorted by relevance score. Empty query returns all available apps.

Inputs: query.

cloudron_task_statusA

Get the status of an async operation (backup, install, restore, etc.) by task ID. Returns state (pending/running/success/error/cancelled), progress (0-100%), and message.

Inputs: taskId (required).

cloudron_uninstall_appA

Uninstall an application with pre-flight safety validation. DESTRUCTIVE OPERATION. First validates via cloudron_validate_operation (checks app exists, no dependencies, backup recommended), then calls DELETE /api/v1/apps/:id. Returns 202 Accepted with task ID for async operation tracking.

Inputs: appId (required).

cloudron_validate_manifestA

Validate app manifest before installation (pre-flight safety check). Checks storage sufficiency via F36, dependency availability, and manifest schema validity. Returns validation report with errors and warnings.

Inputs: appId (required).

cloudron_validate_operationA

Pre-flight validation for destructive operations (uninstall app, delete user, restore backup). Returns validation result with blocking errors, warnings, and recommendations.

Inputs: operation (required), resourceId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no significant overlap. For example, cloudron_control_app handles app lifecycle control, cloudron_configure_app manages configuration updates, and cloudron_get_logs retrieves logs, all targeting different aspects of the Cloudron system. The descriptions clearly differentiate between management, monitoring, validation, and operational tasks.

    Naming Consistency5/5

    All tools follow a consistent snake_case naming pattern with a 'cloudron_' prefix and descriptive verb_noun combinations (e.g., cloudron_list_apps, cloudron_create_backup, cloudron_validate_manifest). This uniformity makes the tool set predictable and easy to navigate, with no deviations in style or structure.

    Tool Count4/5

    With 19 tools, the count is slightly high but reasonable for a comprehensive Cloudron management server covering apps, backups, users, domains, and system operations. It includes essential CRUD operations, validation, and monitoring tools, though it could be streamlined by merging some validation or status-checking tools without losing functionality.

    Completeness5/5

    The tool set provides complete coverage for Cloudron instance management, including app lifecycle (install, configure, control, uninstall, list, search, get), backup operations (create, list), user management (create, list), domain listing, system status, logs, storage checks, and async task handling. There are no obvious gaps, and tools like cloudron_validate_manifest and cloudron_validate_operation ensure safety for destructive operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP Beget

      yasg1988
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for managing Beget hosting services including sites, domains, databases, and mail directly through Claude Code. It provides comprehensive tools for configuring DNS, FTP, Cron jobs, and managing backups via the Beget API.
      3
      MIT

    • ItchWHMMCP

      manofsadness
      A
      license
      B
      quality
      D
      maintenance
      A local MCP server for managing WHM and cPanel servers through AI clients, supporting server health, account, DNS, email, database, SSL, bandwidth, disk, cron, and service-management tools across multiple WHM accounts.
      31
      MIT

    • coolify-mcp

      jurislm
      A
      license
      Not graded
      quality
      F
      maintenance
      MCP server for Coolify infrastructure management, providing 45 tools for servers, applications, databases, deployments, and diagnostics via natural language.
      10 npm
      MIT