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 :

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:

https://www.npmjs.com/package/@halecraft/mcp-cloudron

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.

Cloudron makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server. Find out more or install now.

Cloudron Forum