{"id":49107469,"url":"https://github.com/adityaarsharma/runcloud-server-management-mcp","last_synced_at":"2026-04-21T02:17:59.937Z","repository":{"id":346131772,"uuid":"1188617389","full_name":"adityaarsharma/runcloud-server-management-mcp","owner":"adityaarsharma","description":"Manage your RunCloud server infrastructure through Claude — 128 tools, SSH execution, WordPress quickstart, health scoring, cross-server search, security audit, and full API v3 coverage","archived":false,"fork":false,"pushed_at":"2026-03-22T11:12:06.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T01:52:59.173Z","etag":null,"topics":["claude","claude-code","claude-desktop","devops","lets-encrypt","mcp","mcp-server","model-context-protocol","nginx","php","runcloud","server-automation","server-management","ssh","typescript","web-hosting","wordpress","wordpress-automation"],"latest_commit_sha":null,"homepage":"https://runcloud.io/docs/api/v3","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adityaarsharma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T10:47:54.000Z","updated_at":"2026-03-22T11:28:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adityaarsharma/runcloud-server-management-mcp","commit_stats":null,"previous_names":["adityaarsharma/runcloud-server-management-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/adityaarsharma/runcloud-server-management-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityaarsharma%2Fruncloud-server-management-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityaarsharma%2Fruncloud-server-management-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityaarsharma%2Fruncloud-server-management-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityaarsharma%2Fruncloud-server-management-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adityaarsharma","download_url":"https://codeload.github.com/adityaarsharma/runcloud-server-management-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityaarsharma%2Fruncloud-server-management-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32073522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T01:35:38.224Z","status":"online","status_checked_at":"2026-04-21T02:00:06.111Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","claude-desktop","devops","lets-encrypt","mcp","mcp-server","model-context-protocol","nginx","php","runcloud","server-automation","server-management","ssh","typescript","web-hosting","wordpress","wordpress-automation"],"created_at":"2026-04-21T02:17:59.270Z","updated_at":"2026-04-21T02:17:59.919Z","avatar_url":"https://github.com/adityaarsharma.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RunCloud MCP - Complete Server Management Automation Kit - Manage, Monitor \u0026 Fix Servers On the Go\n\nRunCloud API + Real-Time Monitoring + Self-Healing + Telegram Alerts. 135 tools packed into one MCP server. Manage servers, detect problems, fix them automatically, and get alerts on your phone.\n\n**Control Plane. Observability. Automation. Alerts. All in one.**\n\n[![RunCloud](https://img.shields.io/badge/RunCloud-API%20v3-0066CC?style=flat-square)](https://runcloud.io)\n[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-Compatible-blueviolet?style=flat-square)](https://modelcontextprotocol.io)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=flat-square\u0026logo=typescript)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18+-green?style=flat-square\u0026logo=node.js)](https://nodejs.org)\n[![Tools](https://img.shields.io/badge/Tools-135-orange?style=flat-square)](#full-tool-catalog-135-tools)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)\n\n---\n\n## Why This Exists\n\n[RunCloud](https://runcloud.io) is a server management panel for deploying web apps on any cloud - DigitalOcean, Hetzner, AWS, Vultr, Linode, or bare metal. It has a powerful REST API, but using it means reading docs, writing curl commands, and switching between tabs.\n\nThis MCP server brings three things together into one automation kit:\n\n1. **RunCloud API** - full server management (web apps, databases, SSL, firewall, deployments, cron jobs)\n2. **SSH Monitoring + Self-Healing** - real-time health checks that detect and fix problems automatically\n3. **Telegram Bot** - 24/7 alerts on your phone with one-tap fix buttons\n\nWorks with Claude Desktop and Claude Code. You describe what you want in plain English. The AI handles the API calls, SSH commands, and server fixes.\n\n**Example:**\n\n\u003e *\"Set up a WordPress site on my production server with PHP 8.2, create the database, system user, and install SSL.\"*\n\nSix API calls executed in the right order, with the right parameters. Done.\n\n---\n\n## The Kit - Three Layers\n\n| Layer | What It Does | Requires |\n|-------|-------------|----------|\n| **RunCloud API** (Control Plane) | Full server management - web apps, databases, SSL, domains, firewall, deployments, cron jobs, and more. 128 tools. | RunCloud API key |\n| **SSH Monitoring + Self-Healing** (Observability) | Real-time health checks, auto-fix broken services, kill orphan processes, clean disk space. 7 tools. | SSH access only (any Linux server) |\n| **Telegram Bot** (Alert Layer) | Automated alerts every 10 minutes, inline fix buttons, 15+ commands for remote server control from your phone. | Telegram bot token |\n\n**All three layers work independently.** Use just one, or combine all three. No RunCloud account needed for SSH monitoring. No SSH needed for RunCloud API tools.\n\n---\n\n## Security\n\nServer management tools demand strict security. Here is how every layer is locked down.\n\n### Zero Third-Party Relay\n\n- **All API traffic** goes direct HTTPS to `manage.runcloud.io` - no proxy, no relay, no middleware\n- **All SSH traffic** goes direct to your server - no tunnel service, no intermediary\n- **Telegram bot** communicates directly with the Telegram Bot API from your server\n\n### Credential Protection\n\n- **RunCloud API key** stored only in your local MCP config file - never transmitted anywhere except direct to RunCloud\n- **SSH credentials** passed per-call only - never stored, never cached, never written to disk by this MCP\n- **Telegram bot token** stored in `.env` on your server with `chmod 600` permissions\n\n### Input Validation \u0026 Injection Prevention\n\n- **Shell injection protection** - all SSH inputs sanitized through `shellEscape`, `validatePath`, and `validateServiceName` before execution\n- **Numeric parameter validation** - timeouts, line counts, and port numbers are bounded to safe ranges\n- **SSH output truncated at 1MB** - prevents memory exhaustion from runaway command output\n\n### Error Sanitization\n\n- **Bearer tokens auto-redacted** from all error messages\n- **Passwords auto-redacted** from all error output\n- Error responses never leak credentials, even on unexpected failures\n\n### Network Isolation\n\n- **Fix server** (`fix-server.py`) binds to `127.0.0.1:3011` only - not accessible from outside the server\n- **MCP processes** bind to `127.0.0.1` behind nginx with Bearer token authentication when deployed remotely\n- **Telegram bot** validates every incoming message against your `TELEGRAM_CHAT_ID` - ignores all other users\n\n### Access Control\n\n- `.env` files set to `chmod 600` (owner read/write only)\n- Failed authentication attempts are logged\n- RunCloud API key scope is full read/write - protect the machine where the MCP is configured\n\n---\n\n## What Can You Do With This?\n\n### For Non-Technical Users\n\n- **Ask about your servers in plain English** -\"How's my server doing?\" \"Is anything broken?\" \"Which sites need SSL renewal?\"\n- **Fix problems without touching a terminal** - issues are detected and repaired automatically\n- **Get Telegram alerts on your phone** - know when something goes wrong, tap a button to fix it\n- **Set up WordPress sites in one sentence** - domain, database, user, SSL - all created automatically\n- **Monitor all servers from one place** - health scores, disk usage, memory - across every server you own\n\n### For Developers \u0026 DevOps\n\n- **135 tools covering the entire RunCloud API** - everything the dashboard can do, available programmatically\n- **SSH execution built in** - run any command on any server directly\n- **Compound operations** - WordPress quickstart (6 API calls), multi-server dashboard, cross-server domain search\n- **Self-healing automation** - detects nginx down, high memory, orphan processes, full disks - and fixes them\n- **Works with Claude Desktop and Claude Code** - GUI or terminal, your choice\n\n---\n\n## RunCloud API - Full Server Management (128 Tools)\n\nEverything the RunCloud dashboard can do - faster, in bulk, across all servers at once.\n\n### Not Just an API Wrapper\n\nMost integrations wrap the API 1:1. This goes further with **compound tools** that chain multiple API calls into single operations:\n\n| Tool | What Happens Behind The Scenes |\n|------|-------------------------------|\n| `wordpress_quickstart` | Creates system user, database, DB user, grants access, creates web app, installs WordPress. **Six API calls. One prompt.** |\n| `server_overview` | Server info + health + hardware + services + web apps - fetched simultaneously |\n| `all_servers_health` | Health check across **every server** in your account at once |\n| `multi_server_dashboard` | Every server: name, IP, health score, webapp count, memory %, disk % - one view |\n| `webapp_inventory` | Every webapp across every server - domain, PHP, stack mode - one table |\n| `ssl_expiry_check` | Scans all web apps on a server, flags expired and expiring-soon certs |\n| `find_webapp_by_domain` | Searches **all servers** for a domain - returns which server it's on |\n| `failed_services_scan` | Scans all servers, returns only stopped/failed services - instant incident detection |\n| `deploy_and_verify` | Force deploy + check webapp status + tail logs - full deploy cycle in one step |\n| `server_health_score` | Calculates a 0-100 score with letter grade (A-F) based on memory, disk, load, services |\n\n### Example Prompts - RunCloud API\n\n```\n\"Give me a full dashboard of all my servers\"\n\"Which servers have memory above 80%?\"\n\"Are there any stopped services across any of my servers?\"\n\"Set up a WordPress site on server 12345 with domain myblog.com, PHP 8.2, and SSL\"\n\"Deploy the latest changes from main branch to webapp 789 and verify it worked\"\n\"Which server is example.com on?\"\n\"Install a Let's Encrypt certificate for myblog.com\"\n\"Block all traffic to port 8080 except from IP 203.0.113.5\"\n\"Show me the full security audit for server 12345\"\n```\n\n---\n\n## Server Monitoring \u0026 Self-Healing (7 SSH Tools)\n\nThese work on **any Linux server** - RunCloud-managed or not. No API key needed. Just SSH access.\n\n### What It Monitors\n\n| Tool | What It Does |\n|------|-------------|\n| `ssh_server_status` | Full health report: RAM, disk, CPU load, nginx status, orphan process count, top 5 processes by memory |\n| `ssh_smart_fix` | Detects and auto-fixes: nginx down, orphan processes, high memory, full disk. Reports exactly what was fixed. |\n| `ssh_restart_service` | Restart any service via SSH. Auto-detects `nginx-rc` (RunCloud) vs `nginx`. Handles `n8n`, `pm2`, any systemd service. |\n| `ssh_kill_orphans` | Finds processes with PPID=1 (true orphans). Dry-run by default. Filter by process name. Safe - skips system processes. |\n| `ssh_disk_cleanup` | Lists large log files. Dry-run by default. Pass `dryRun: false` to clear. Configurable minimum size. |\n| `ssh_check_ports` | All listening ports with PID and process name. Optional filter to specific ports. |\n| `telegram_send_alert` | Send a Markdown message to any Telegram chat. Optionally include action buttons (Status, Smart Fix, Nginx, Disk, Ignore). |\n\n### What `ssh_smart_fix` Detects and Repairs\n\n```\nProblem detected               →  Action taken\n─────────────────────────────────────────────────\nnginx-rc / nginx is not active →  sudo systemctl restart nginx-rc (or nginx)\nOrphan procs (PPID=1) \u003e 10    →  Kill all orphan PIDs\nMemory usage \u003e 88%             →  pm2 restart all (finds pm2 automatically)\nDisk usage \u003e 88%               →  truncate - s 0 on log files \u003e 50MB\nAll clear                      →  Reports \"healthy - nothing needed fixing\"\n```\n\n### RunCloud-Specific: nginx-rc Detection\n\nRunCloud installs its own nginx binary (`nginx-rc`) instead of standard `nginx`. Most monitoring tools check the wrong service name and report \"inactive\" even when the web server is running fine.\n\nAll SSH tools in this MCP auto-detect which one is running:\n\n```\nsystemctl is-active nginx-rc   →  active  →  use nginx-rc\nsystemctl is-active nginx-rc   →  inactive →  fall back to nginx\n```\n\nYou can also pass `nginxService: \"nginx-rc\"` explicitly to skip detection.\n\n### Example Prompts - Monitoring\n\n```\n\"Check the status of my server at 95.216.156.89\"\n\"Run a smart fix on my server - detect and repair any issues\"\n\"Kill orphan processes on my server (dry run first)\"\n\"Restart nginx on my server - it uses RunCloud so try nginx-rc first\"\n\"Show me all listening ports on my server\"\n\"Find log files over 100MB and clear them\"\n```\n\n---\n\n## Telegram Bot - Monitor \u0026 Fix from Your Phone\n\nA complete standalone monitoring and alerting layer. Runs on your server with zero external dependencies beyond Python.\n\n### How It Works\n\n```\nYour Server\n├── monitor.sh        ← Cron every 10 min → detects issues → sends Telegram alerts\n├── fix-server.py     ← Local HTTP API on 127.0.0.1:3011 → executes fix scripts\n├── bot.py            ← Telegram bot (polling) → handles commands + button callbacks\n└── .env              ← All config in one file (chmod 600)\n```\n\n**monitor.sh** runs every 10 minutes via cron. If it detects a problem (nginx down, high memory, disk full), it sends a Telegram message with inline action buttons. Tap a button, the fix runs instantly, you see the result in chat.\n\n### Telegram Commands\n\n| Command | What It Does |\n|---------|-------------|\n| `/status` | Full RAM, Disk, CPU, nginx, services status |\n| `/brief` | One-liner quick status |\n| `/fix` | Smart fix - auto-detect and repair all issues |\n| `/nginx` | Restart nginx / nginx-rc |\n| `/n8n` | Restart n8n |\n| `/services` | Restart all custom services |\n| `/disk` | Disk usage breakdown |\n| `/logs` | Clear large log files |\n| `/ports` | Check which service ports are responding |\n| `/mute 2h` | Silence alerts for 2 hours |\n| `/mute 30m` | Silence for 30 minutes |\n| `/unmute` | Re-enable alerts |\n| `/test` | Send a test alert |\n| `/reboot` | Reboot server (inline confirmation required) |\n| `/menu` | Show action button keyboard |\n| `/help` | All commands |\n\n### Alert Buttons\n\nWhen monitor.sh detects a problem, the Telegram message includes inline buttons:\n\n```\nSmart Fix    Status\nNginx        Disk    Ignore\n```\n\nTap a button, the fix runs, the result appears in the same chat. Works even when the Telegram bot service is stopped - the fix server handles callbacks independently.\n\n### Telegram Setup\n\n```bash\ncd telegram-bot\ncp config.example.env .env\nnano .env   # Add TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID\nbash setup.sh\n```\n\n`setup.sh` handles everything:\n1. Writes `.env` with all config\n2. Generates a random auth token for the fix server\n3. Installs Python `requests` dependency\n4. Sets up the cron for `monitor.sh`\n5. Creates and starts systemd services for `bot.py` and `fix-server.py`\n6. Sends a test Telegram message to confirm it works\n\n**To get Telegram credentials:**\n- **Bot token:** Message [@BotFather](https://t.me/BotFather) on Telegram, run `/newbot`, copy the token\n- **Chat ID:** Message [@userinfobot](https://t.me/userinfobot) on Telegram, it replies with your chat ID\n\n---\n\n## Installation\n\n### MCP Server (Claude Desktop or Claude Code)\n\n**1. Clone and build**\n\n```bash\ngit clone https://github.com/adityaarsharma/runcloud-server-management-mcp.git\ncd runcloud-server-management-mcp\nnpm install\nnpm run build\n```\n\n**2. Configure Claude Desktop**\n\nOpen the config file:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"runcloud\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/runcloud-server-management-mcp/dist/index.js\"],\n      \"env\": {\n        \"RUNCLOUD_API_KEY\": \"your_runcloud_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n\u003e **No RunCloud API key?** Remove the `RUNCLOUD_API_KEY` line entirely. The 7 SSH monitoring/self-healing tools still work. You'll only get an error if you try to use a RunCloud API tool.\n\n**3. Restart Claude Desktop**\n\nThe MCP server starts automatically. You'll see a hammer icon in Claude Desktop confirming tools are loaded.\n\n**4. Claude Code (terminal)**\n\n```bash\nclaude mcp add runcloud node /absolute/path/to/dist/index.js \\\n  - e RUNCLOUD_API_KEY=your_runcloud_api_key_here\n```\n\nOr without API key (SSH monitoring tools only):\n\n```bash\nclaude mcp add runcloud node /absolute/path/to/dist/index.js\n```\n\n**5. Via supergateway (for remote/shared access)**\n\n```bash\nnpm install - g supergateway\nsupergateway --stdio \"node /path/to/dist/index.js\" \\\n  --port 3020 \\\n  --outputTransport streamableHttp \\\n  --path /mcp \\\n  --oauth2Bearer your_secret_token \\\n  --logLevel none\n```\n\nThen in Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"runcloud\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://your-server.com:3020/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_secret_token\"\n      }\n    }\n  }\n}\n```\n\n### Getting Your RunCloud API Key\n\n1. Log into [RunCloud](https://runcloud.io)\n2. Go to **Settings, then API Management**\n3. Create a new API key\n4. Copy the key - you won't see it again\n\nThe API key gives full read/write access to everything in your RunCloud account. Store it only in your local config file - never commit it to Git.\n\n---\n\n## Full Tool Catalog (135 Tools)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eServers -17 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_servers` | List all servers. Supports `all: true` for auto-pagination. |\n| `list_shared_servers` | Servers shared with your account |\n| `get_server` | Full server details by ID |\n| `create_server` | Add a new server (works with any provider) |\n| `delete_server` | Remove a server from RunCloud |\n| `get_server_stats` | Web app count, database count, cron count, geo location |\n| `get_server_hardware_info` | CPU, RAM, disk, load average, kernel version, uptime |\n| `get_server_health` | Latest health data snapshot from RunCloud agent |\n| `clean_server_disk` | Trigger disk cleanup via RunCloud |\n| `get_installation_script` | Get the RunCloud agent install script for a server |\n| `get_server_logs` | Action and change logs for a server |\n| `get_ssh_settings` | SSH config: passwordless login, DNS, root login settings |\n| `update_ssh_settings` | Modify SSH configuration |\n| `update_server_meta` | Rename server or change provider label |\n| `update_server_autoupdate` | Configure automatic OS and security updates |\n| `list_php_versions` | Available PHP versions installed on a server |\n| `change_php_cli` | Set the default PHP CLI version |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWeb Applications -12 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_webapps` | All web apps on a server. Supports `all: true`. |\n| `get_webapp` | Full details for a specific web app |\n| `create_webapp` | Create a web app (Native, Custom, or WordPress stack) |\n| `delete_webapp` | Delete a web app |\n| `rebuild_webapp` | Rebuild nginx + PHP config for a web app |\n| `get_webapp_settings` | PHP-FPM settings, memory, upload size |\n| `update_webapp_fpm_settings` | Update PHP-FPM pool settings |\n| `get_webapp_logs` | Recent logs for a web app |\n| `set_webapp_default` | Set a web app as the server's default |\n| `remove_webapp_default` | Remove the default flag |\n| `create_webapp_alias` | Add an alias/subdomain to a web app |\n| `change_webapp_php_version` | Switch PHP version for a web app |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePHP Script Installer -3 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_script_installers` | Available one-click installers (WordPress, Joomla, Drupal, phpMyAdmin, etc.) |\n| `install_php_script` | Run a one-click installer on a web app |\n| `remove_php_installer` | Remove a script installer from a web app |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGit \u0026 Deployments -6 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `get_git_info` | Current git connection details for a web app |\n| `clone_git_repo` | Connect a git repository to a web app |\n| `remove_git_repo` | Disconnect git from a web app |\n| `change_git_branch` | Switch the active branch |\n| `force_git_deploy` | Force a git pull and deploy |\n| `update_git_deploy_script` | Modify the post-deploy script |\n| `generate_deployment_key` | Generate an SSH deploy key for private repos |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDomains -3 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_domains` | All domain names attached to a web app |\n| `add_domain` | Add a domain or subdomain to a web app |\n| `delete_domain` | Remove a domain from a web app |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSSL Certificates -10 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `get_ssl` | Current SSL cert info for a web app |\n| `install_ssl` | Install Let's Encrypt or custom SSL |\n| `delete_ssl` | Remove SSL from a web app |\n| `redeploy_ssl` | Force SSL redeployment |\n| `get_domain_ssl` | Per-domain SSL info |\n| `install_domain_ssl` | Install SSL for a specific domain |\n| `delete_domain_ssl` | Remove domain-level SSL |\n| `redeploy_domain_ssl` | Force redeploy domain SSL |\n| `get_advanced_ssl` | Advanced SSL config details |\n| `switch_advanced_ssl` | Toggle advanced SSL settings |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDatabases -12 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_databases` | All databases on a server |\n| `get_database` | Details for a specific database |\n| `create_database` | Create a new database |\n| `delete_database` | Delete a database |\n| `list_database_users` | All database users on a server |\n| `get_database_user` | Details for a specific DB user |\n| `create_database_user` | Create a database user |\n| `delete_database_user` | Delete a database user |\n| `update_database_user_password` | Change a DB user's password |\n| `list_granted_database_users` | Users with access to a specific database |\n| `grant_database_user` | Grant a user access to a database |\n| `revoke_database_user` | Revoke user access from a database |\n| `list_database_collations` | Available character sets and collations |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSystem Users -6 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_system_users` | All system users on a server |\n| `get_system_user` | Details for a specific system user |\n| `create_system_user` | Create a system user (for web apps) |\n| `delete_system_user` | Delete a system user |\n| `change_system_user_password` | Set or change password (also needed for SSH login) |\n| `generate_deployment_key` | Generate SSH deploy key for a system user |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSSH Keys -4 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_ssh_keys` | All public SSH keys on a server |\n| `get_ssh_key` | Details for a specific SSH key |\n| `add_ssh_key` | Add a public SSH key to a server |\n| `delete_ssh_key` | Remove an SSH key |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCron Jobs -5 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_cronjobs` | All cron jobs on a server |\n| `get_cronjob` | Details for a specific cron job |\n| `create_cronjob` | Create a new cron job |\n| `delete_cronjob` | Delete a cron job |\n| `rebuild_cronjobs` | Rebuild the crontab file |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSupervisor -8 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_supervisor_jobs` | All Supervisor background workers |\n| `get_supervisor_job` | Details for a specific worker |\n| `create_supervisor_job` | Create a new background worker |\n| `delete_supervisor_job` | Delete a worker |\n| `reload_supervisor_job` | Reload a specific worker |\n| `rebuild_supervisor_jobs` | Rebuild all Supervisor configs |\n| `get_supervisor_status` | Current status of all workers |\n| `list_supervisor_binaries` | Available binary paths for Supervisor |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFirewall \u0026 Security -9 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_firewall_rules` | All firewall rules on a server |\n| `create_firewall_rule` | Add a firewall rule (IP whitelist, port block, etc.) |\n| `delete_firewall_rule` | Remove a firewall rule |\n| `deploy_firewall_rules` | Apply pending firewall changes |\n| `list_fail2ban_blocked_ips` | IPs currently blocked by Fail2Ban |\n| `unblock_fail2ban_ip` | Unblock a specific IP from Fail2Ban |\n| `security_audit` | Full snapshot: firewall + SSH keys + Fail2Ban + external APIs |\n| `open_ports_report` | Ports open to 0.0.0.0 - review before going live |\n| `list_ssl_protocols` | Available SSL/TLS protocol versions |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eServices -2 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_services` | All services (nginx, mysql, redis, etc.) with CPU, memory, version |\n| `control_service` | Start, stop, restart, or reload any service via RunCloud API |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExternal APIs -5 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `list_external_apis` | All connected third-party API keys |\n| `get_external_api` | Details for a specific external API |\n| `create_external_api` | Add a new external API (Cloudflare, DigitalOcean, etc.) |\n| `update_external_api` | Update an external API connection |\n| `delete_external_api` | Remove an external API |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCross-Server Search \u0026 Inventory -4 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `find_webapp_by_domain` | Search all servers for a domain name - returns server + webapp |\n| `webapp_inventory` | Full inventory: every webapp across all servers in one table |\n| `multi_server_dashboard` | All servers: health score, webapp count, memory%, disk% |\n| `failed_services_scan` | All servers: only stopped/failed services - instant incident detection |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHealth, Monitoring \u0026 Performance -7 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `server_overview` | Full server snapshot: info + health + hardware + services + webapps |\n| `server_health_score` | 0-100 score + letter grade (A-F) based on RAM, disk, load, services |\n| `all_servers_health` | Health status across every server in your account |\n| `server_load_report` | CPU, memory, disk, and load trends via SSH |\n| `nginx_top_ips` | Top IPs hitting nginx - detect scrapers and attackers |\n| `php_error_summary` | PHP error counts by type + last 20 lines from error log |\n| `ssl_expiry_check` | Scans all web apps, flags EXPIRED and EXPIRING_SOON certs |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDeployments -2 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `deploy_and_verify` | Force deploy + check webapp status + tail logs - one step |\n| `wordpress_quickstart` | Full WordPress setup: user + DB + web app + install - one prompt |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWordPress Management (SSH) -5 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `ssh_wp_cli` | Run any WP-CLI command on any web app |\n| `wp_health_check` | WP core checksums + active plugins + cron status |\n| `wp_outdated_plugins` | List plugins with available updates |\n| `wp_admin_audit` | All admin users - detect unexpected accounts |\n| `wp_clear_all_caches` | Flush WordPress + Redis + OPcache |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSSH Direct Execution -4 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `ssh_run_command` | Run any shell command on any server via SSH |\n| `ssh_artisan` | Run Laravel Artisan commands |\n| `ssh_tail_log` | Live tail a log file (returns last N lines) |\n| `ping` | Test API authentication |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eServer Monitoring \u0026 Self-Healing (SSH-direct) -7 tools\u003c/strong\u003e\u003c/summary\u003e\n\n| Tool | Description |\n|------|-------------|\n| `ssh_server_status` | Full health report: RAM, disk, CPU load, nginx/nginx-rc status, orphan count, top 5 processes |\n| `ssh_smart_fix` | Auto-detect and fix: nginx down, orphan procs, high memory, full disk |\n| `ssh_restart_service` | Restart any service. Auto-detects nginx-rc vs nginx. |\n| `ssh_kill_orphans` | Find and kill orphan processes (PPID=1). Dry-run by default. |\n| `ssh_disk_cleanup` | Find and clear large log files. Dry-run by default. |\n| `ssh_check_ports` | All listening ports with PID and process name. |\n| `telegram_send_alert` | Send Markdown message to Telegram with optional action buttons. |\n\n\u003c/details\u003e\n\n---\n\n## SSH Tools - How Server Connections Work\n\n**With RunCloud API:** Pass a `serverId` - the server IP is fetched automatically from RunCloud. You never need to look it up.\n\n**Without RunCloud API:** Pass `host` directly to any SSH monitoring tool. No API key needed.\n\n```\nWith API:    \"List my servers\" → \"SSH into server 12345 as deploy and run ls\"\nWithout API: \"Check server status at 95.216.156.89 - SSH as runcloud / mypassword\"\n```\n\n### System Users Are Required for SSH\n\nRunCloud uses isolated system users per web app. SSH tools need a username and password:\n\n```\n\"Set the password for system user 99 on server 12345 to MyPass123\"\n```\n\nThen use that username and password in all SSH tool calls.\n\n### RunCloud Agent vs SSH - Two Ways to Check Health\n\n- `get_server_health` - Uses RunCloud's agent data (polled every minute by RunCloud). Slight delay.\n- `ssh_server_status` - Runs commands directly on the server. Real-time. Works even if the RunCloud agent is slow.\n\n---\n\n## Project Structure\n\n```\nruncloud-server-management-mcp/\n│\n├── src/\n│   └── index.ts              ← Full MCP server - all 135 tools\n│\n├── dist/                     ← Compiled JavaScript (auto-generated)\n│   └── index.js\n│\n├── telegram-bot/             ← Standalone Telegram monitoring stack\n│   ├── bot.py                ← Telegram bot (polling, no library needed)\n│   ├── fix-server.py         ← Local HTTP fix API (127.0.0.1:3011)\n│   ├── monitor.sh            ← Cron monitor (alerts + dedup + mute)\n│   ├── setup.sh              ← One-command setup wizard\n│   └── config.example.env    ← All config documented\n│\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## Dependencies\n\n### MCP Server\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| **Node.js** | 18+ | Runtime (built-in `fetch()`) |\n| **npm** | 8+ | Package manager |\n| `@modelcontextprotocol/sdk` | latest | MCP protocol - how AI clients communicate with this server |\n| `ssh2` | ^1.x | SSH client - enables direct server connections |\n| **TypeScript** | 5.x | Source language |\n\nNo database. No background services. No port forwarding. The MCP server is a process spawned by the AI client when you open it.\n\n### Telegram Bot (optional)\n\n| Dependency | Version | Purpose |\n|------------|---------|---------|\n| **Python** | 3.8+ | Runtime for bot and fix server |\n| `requests` | any | HTTP calls to Telegram API |\n| **bash** | 4+ | For monitor.sh |\n| `jq` | any | JSON formatting |\n| `curl` | any | HTTP in monitor.sh |\n| `nc` (netcat) | any | Port checking |\n| **systemd** | any | Runs bot and fix server as services |\n| **cron** | any | Runs monitor.sh every 10 minutes |\n\nNo Telegram bot library needed - uses the raw Telegram Bot API.\n\n---\n\n## Built With\n\n| Library | Purpose |\n|---------|---------|\n| [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) | MCP protocol implementation |\n| [`ssh2`](https://github.com/mscdex/ssh2) | SSH client for Node.js |\n| [RunCloud API v3](https://runcloud.io/docs/api/v3) | Server management REST API |\n| TypeScript 5 + Node.js 18 | Language and runtime |\n| Python 3 + requests | Telegram bot and monitoring |\n\n---\n\n## Contributing\n\nPRs welcome. Ideas:\n\n- More compound tools (e.g. `migrate_webapp` - clone a webapp to another server)\n- Discord notification support in monitor.sh\n- RunCloud webhook receiver\n- Multi-account support (multiple API keys)\n- Health history tracking\n\n---\n\n## Related Projects\n\n- **[YouTube Channel Data MCP](https://github.com/adityaarsharma/youtube-channel-data-mcp)** - Connect Claude to your YouTube Analytics data\n\n---\n\n## License\n\nMIT - use it, modify it, ship it.\n\n---\n\n## About\n\nBuilt by **[Aditya Sharma](https://adityaarsharma.com)** - marketing and growth at [POSIMYTH](https://posimyth.com), makers of WordPress tools.\n\n- [adityaarsharma.com](https://adityaarsharma.com)\n- [@adityaarsharma on X](https://twitter.com/adityaarsharma)\n- [github.com/adityaarsharma](https://github.com/adityaarsharma)\n\nIf this saved you time -**star the repo**\n\n---\n\n*Not an official RunCloud product. Built independently using the [RunCloud public API v3](https://runcloud.io/docs/api/v3).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityaarsharma%2Fruncloud-server-management-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadityaarsharma%2Fruncloud-server-management-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityaarsharma%2Fruncloud-server-management-mcp/lists"}