MCP Server for Cloudron - AI-Powered Instance Management

sangemaru

Hello Cloudron Community!

I'm excited to share mcp-cloudron - an open-source MCP (Model Context Protocol) server that lets AI assistants interact with your Cloudron instance.

What is MCP?

MCP is Anthropic's open standard for connecting AI assistants (like Claude) to external tools and data sources. This server gives AI agents the ability to query and manage your Cloudron instance programmatically.

Current Features (v1.0.0)

List Applications - See all installed apps with status, health, domain, and resource usage
Get App Details - Detailed information on specific applications by ID
Instance Status - Query Cloudron version, configuration, and system info

Quick Start

Install via npm:

npm install @serenichron/mcp-cloudron

Configuration: You'll need a Cloudron API token (Settings → API Tokens). Then add to your MCP client configuration:

{
  "mcpServers": {
    "cloudron": {
      "command": "npx",
      "args": ["-y", "@serenichron/mcp-cloudron"],
      "env": {
        "CLOUDRON_DOMAIN": "your-cloudron.example.com",
        "CLOUDRON_TOKEN": "your-api-token"
      }
    }
  }
}

Use Cases

With this MCP server, AI assistants can:

Monitor app health and status across your instance
Get detailed resource usage and configuration info
Help troubleshoot issues by querying app states
Provide intelligent suggestions based on your Cloudron setup

Links

npm Package: https://www.npmjs.com/package/@serenichron/mcp-cloudron
GitHub Repository: https://github.com/serenichron/mcp-cloudron
Documentation: Full setup guide and API reference in README

Roadmap

Future features planned for upcoming releases:

App lifecycle management (start/stop/restart/uninstall)
App installation from the App Store
Backup and restore operations
Log access and monitoring
Event subscriptions and webhooks

Security Note

The server uses read-only operations in v1.0.0 (list apps, get status). Future write operations will include appropriate safety checks and confirmations. Always use dedicated API tokens with minimal required permissions.

Contributions Welcome!

This project is MIT licensed and I'd love community input:

Feature Requests: What Cloudron operations would be most useful for AI automation?
Bug Reports: Issues and feedback on GitHub
Pull Requests: Code contributions welcome!
Integration Ideas: How are you using it? Share your use cases!

Testing & Compatibility

Tested with Cloudron 8.2.0+
Works with Claude Desktop, Continue.dev, and other MCP-compatible clients
Node.js 18+ required

Looking forward to your feedback and suggestions!

james

Hello @sangemaru and welcome to the Cloudron Community

timconsidine

If current focus is on GET instance info, retrieving a list of domains might be good addition.

sangemaru

I've published v0.2.0 of the Cloudron MCP server on npm. This release includes 15 tools from Phase 1, but 8 of them I couldn't fully test.

Confirmed Working (7 tools)

Listing & Read Operations:

cloudron_list_apps - List all apps
cloudron_get_app - Get app details
cloudron_get_status - Get Cloudron status
cloudron_list_backups - List backups
cloudron_list_users - List users
cloudron_search_apps - Search App Store

System Operations:

cloudron_check_storage - Check disk space

These work reliably and return proper JSON results.

️ Needs Testing (8 tools)

Async Operations (return task IDs, need manual verification):

cloudron_task_status - Monitor async task progress
cloudron_cancel_task - Cancel running tasks
cloudron_control_app - Start/stop/restart apps
cloudron_create_backup - Create new backup (returns task ID)
cloudron_uninstall_app - Uninstall app (returns task ID)

Validation & Configuration:

cloudron_validate_operation - Pre-flight safety checks
cloudron_validate_manifest - App manifest validation
cloudron_configure_app - App configuration changes

Known Issues

cloudron_validate_manifest:

️ Currently returns mock validation only

Critical Bugs Fixed

cloudron_search_apps:

Fixed: Was returning empty results due to incomplete pagination handling
Now properly aggregates results across all pages

F04 (cloudron_uninstall_app):

Fixed: Pre-flight validation check was incorrect
Now properly validates with cloudron_validate_operation before uninstall

Installation

npm install -g @serenichron/mcp-cloudron

Add to your MCP client of choice:

{
  "mcpServers": {
    "cloudron": {
      "command": "npx",
      "args": ["-y", "@serenichron/mcp-cloudron"],
      "env": {
        "CLOUDRON_HOST": "your-cloudron.example.com",
        "CLOUDRON_TOKEN": "your-api-token"
      }
    }
  }
}

Get your API token: https://your-cloudron.example.com/settings.html#account

Can You Help Test?

If you have a Cloudron instance and want to help validate these tools:

Async operations: Test task status monitoring with actual app operations
Backups: Verify backup creation works end-to-end
App control: Test start/stop/restart operations
Validation: Try pre-flight checks with real scenarios

Reporting bugs: Please open issues at github.com/serenichron/mcp-cloudron/issues

What's Next (Phase 2)

Once we validate these 15 tools, Phase 2 will add:

App installation workflow
User management (create/update/delete)
Backup restore operations
Enhanced logging and debugging
Domain management

Thanks for any testing help!

Package: @serenichron/mcp-cloudron v0.2.0
Cloudron version: 9.0.15

sangemaru

@james :