MCP Server for Cloudron - AI-Powered Instance Management

[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:

1. Async operations: Test task status monitoring with actual app operations
2. Backups: Verify backup creation works end-to-end
3. App control: Test start/stop/restart operations
4. 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 :

Hello @sangemaru and welcome to the Cloudron Community

It's good to be here. Thank you for the work you do on this excellent project.

@timconsidine :

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

Noted and appreciated. Took a note to weave that in. My intention is to eventually support the full API.

[ekevu123]

This is impressive. I think an MCP server should be part of the core Cloudron software some time soon!

I am not familiar with the Cloudron API, can I use this to get the logs of an individual app, or only its status?

[joseph]

There's also this "toy" from @girish at https://forum.cloudron.io/topic/13999/mcp-server-for-apps/11

[sangemaru]

@ekevu123 You can use Cloudron CLI to get the logs from apps. I'll see about possibly adding that in at some point.

[sangemaru]

@joseph Yup. Hasn't been updated in 9 months though, so I wanted to try and make a full-featured one.

[canadaduane]

With apologies in advance to @sangemaru (since I did not ask permission), I've forked this project.

• the git repository's source code is in a poor state
  • node_modules checked into source code
  • dist checked into source code
  • multiple megabytes of executables and directories not compatible across operating systems
  • many leftover markdown files, plans, unused files throughout
  • tests not working, and typescript unused
• Since I used a filter-repo to clean up the git history, this made my changes incompatible with github PRs

Subset of filter-repo commands used during cleanup:

git filter-repo --force --path node_modules --invert-paths
git filter-repo --force --path dist --invert-paths
git filter-repo --force --path TESTING.md --invert-paths
git filter-repo --force --path PHASE_2_3_SUMMARY.md --invert-paths
git filter-repo --force --path .serena --invert-paths
git filter-repo --force --path FORUM_POST.md --invert-paths
git filter-repo --force --path REAL_TEST_RESULTS_F23B.md
git filter-repo --force --path TESTING_NOTES.md --invert-paths

Here is the new published package:

Just a moment...

(www.npmjs.com)

I separated the API surface area into 8 categories for now, and implemented a few more of the openapi spec endpoints (32 of 240 total implemented):

App Management

• cloudron_list_apps - List all installed applications with status and health
• cloudron_get_app - Get detailed information about a specific application
• cloudron_control_app - Start, stop, or restart an application
• cloudron_configure_app - Update environment variables, memory limits, access control
• cloudron_install_app - Install an application from the App Store
• cloudron_uninstall_app - Uninstall an application (with pre-flight validation)
• cloudron_clone_app - Clone an application to a new location
• cloudron_repair_app - Repair a broken application
• cloudron_update_app - Update an application to a newer version
• cloudron_restore_app - Restore an application from a backup
• cloudron_backup_app - Create a backup of a specific application

App Store

• cloudron_search_apps - Search the Cloudron App Store
• cloudron_validate_manifest - Validate an app before installation

Backups

• cloudron_list_backups - List all available backups
• cloudron_create_backup - Create a new instance backup

Users

• cloudron_list_users - List all users
• cloudron_get_user - Get details for a specific user
• cloudron_create_user - Create a new user with role assignment
• cloudron_update_user - Update user properties (email, role, password)
• cloudron_delete_user - Delete a user (with pre-flight validation)

Groups

• cloudron_list_groups - List all groups
• cloudron_create_group - Create a new group

System

• cloudron_get_status - Get Cloudron instance status and version
• cloudron_check_storage - Check available disk space
• cloudron_list_services - List platform services (MySQL, PostgreSQL, etc.)
• cloudron_list_domains - List configured domains
• cloudron_get_logs - Retrieve application or service logs

Tasks

• cloudron_task_status - Check status of an async operation
• cloudron_cancel_task - Cancel a running operation
• cloudron_validate_operation - Pre-flight validation for destructive operations

Updates

• cloudron_check_updates - Check for Cloudron platform updates
• cloudron_apply_update - Apply a platform update

I don't normally do this (I like to contribute), but I have some time constraints right now and am currently unwilling to slow down to work through some of these issues to get to baseline. That said, I do applaud your getting this started sangemaru and hope this doesn't dissuade you from continuing.

[sangemaru]

Much appreciated @canadaduane, thanks for the feedback. Would be great if you can make your fork repo public. For me it's very much a learning experience, since I'm not a software developer by trade.

And, I hope you'll excuse the pun, but you could totally rock "The Rock" Johnson as a nickname.