Cloudron Forum

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!

Business owner with sysadmin background here. I use Cloudron to power apps for my business.

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

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.

@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.

Description

Aplication not responding. Investigated logs show database migration error.

Steps to reproduce

Vaultwarden App updated to 1.23.0

Logs

2025-12-30T08:56:20Z /--------------------------------------------------------------------\
2025-12-30T08:56:20Z 0: vaultwarden::init_logging::{{closure}}
2025-12-30T08:56:20Z 10: std::sys::backtrace::__rust_begin_short_backtrace
2025-12-30T08:56:20Z 11: main
2025-12-30T08:56:20Z 12: <unknown>
2025-12-30T08:56:20Z 13: __libc_start_main
2025-12-30T08:56:20Z 14: _start
2025-12-30T08:56:20Z 1: std::panicking::panic_with_hook
2025-12-30T08:56:20Z 2: std::panicking::panic_handler::{{closure}}
2025-12-30T08:56:20Z 3: std::sys::backtrace::__rust_end_short_backtrace
2025-12-30T08:56:20Z 4: __rustc::rust_begin_unwind
2025-12-30T08:56:20Z 5: core::panicking::panic_fmt
2025-12-30T08:56:20Z 6: core::result::unwrap_failed
2025-12-30T08:56:20Z 7: vaultwarden::db::DbPool::from_config
2025-12-30T08:56:20Z 8: vaultwarden::main::{{closure}}
2025-12-30T08:56:20Z 9: vaultwarden::main
2025-12-30T08:56:20Z => Exporting env vars expected by Vaultwarden
2025-12-30T08:56:20Z => Starting Bitwarden
2025-12-30T08:56:20Z Please generate a secure Argon2 PHC string by using `vaultwarden hash` or `argon2`.
2025-12-30T08:56:20Z See: https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page#secure-the-admin_token
2025-12-30T08:56:20Z [2025-12-30 08:56:20.876][panic][ERROR] thread 'main' panicked at 'Error running migrations: QueryError(DieselMigrationName { name: "2024-03-06-170000_add_sso_users", version: MigrationVersion("20240306170000") }, DatabaseError(Unknown, "Referencing column 'user_uuid' and referenced column 'uuid' in foreign key constraint 'sso_users_ibfk_1' are incompatible."))': src/db/mod.rs:505

Troubleshooting Already Performed

Restored 1.22.2 application Backup restored functionality

System Details

Generate Diagnostics Data

Diagnostic Data sent to support@cloudron.io

Cloudron Version

9.0.15

Ubuntu Version

Distributor ID:	Ubuntu
Description:	Ubuntu 24.04.3 LTS
Release:	24.04
Codename:	noble

Cloudron installation method

• Manual with ./cloudron-setup

Output of cloudron-support --troubleshoot

Vendor: netcup Product: KVM Server
Linux: 6.8.0-90-generic
Ubuntu: noble 24.04
Execution environment: kvm
Processor: AMD EPYC 9645 96-Core Processor
BIOS pc-i440fx-9.2  CPU @ 2.0GHz x 8
RAM: 16370004KB
Disk: /dev/vda1       425G
[OK]	node version is correct
[OK]	IPv6 is enabled and public IPv6 address is working
[OK]	docker is running
[OK]	docker version is correct
[OK]	MySQL is running
[OK]	nginx is running
[OK]	dashboard cert is valid
[OK]	dashboard is reachable via loopback
[OK]	No pending database migrations
[OK]	Service 'mysql' is running and healthy
[OK]	Service 'postgresql' is running and healthy
[OK]	Service 'mongodb' is running and healthy
[OK]	Service 'mail' is running and healthy
[OK]	Service 'graphite' is running and healthy
[OK]	Service 'sftp' is running and healthy
[OK]	box v9.0.15 is running
[OK]	netplan is good
[OK]	DNS is resolving via systemd-resolved
[OK]	Dashboard is reachable via domain name
[WARN]	Domain serenichron.agency expiry check skipped because whois does not have this information
[OK]	unbound is running

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

@james I also confirm this worked.

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