kroomboxpanel-mcp

Official Model Context Protocol (MCP) server for Kroombox Panel.

This package provides AI assistants—such as Google Antigravity (agy), Cursor IDE, Claude Desktop, Windsurf, and Zed—with secure, multi-tenant scoped execution power over cloud web hosting, zero-downtime application deployments, PM2 processes, MySQL databases, live server logs, remote file management, and Git workflows.

Highlights & Features

• Zero-Install Portability: Run instantly using npx -y kroomboxpanel-mcp or connect via Remote HTTP Server-Sent Events (SSE) without downloading anything.
• Fine-Grained Security Scoping: Strictly enforced per-token role-based permissions with wildcard scope matching (e.g. sites:read, files:write, databases:*, terminal:exec).
• Full-Stack Lifecycle Management: Deploy Node.js, React, Next.js, Python, and static sites. Start, stop, reload, and monitor PM2 processes in real-time.
• Database Automation: Provision isolated MySQL tenant databases, manage credentials, and export backups on demand.
• Cloud Workspace File Manager: Read, write, rename, copy, move, and edit configuration files directly in tenant directories.
• Git Version Control: Pull updates from remote repositories, inspect branch status, check commit histories, and switch branches.
• Telemetry & Analytics: Inspect server health, resource consumption (CPU, RAM, Disk), and visitor traffic analytics.
• Dual Transport Support: Works seamlessly via local Stdio JSON-RPC 2.0 or high-performance cloud HTTP SSE stream.
• 56 Specialized Tools: Comprehensive coverage across 14 modules.

Installation & Quickstart

Option 1: Zero-Install via npx (Recommended for Local Stdio)

Run directly without installing:

npx -y kroomboxpanel-mcp --url https://panel.kroombox.com --token kp_live_your_token_here

Option 2: Remote SSE Stream (Recommended for Cloud / Zero-Footprint)

No Node.js or local installation required on your client machine:

https://panel.kroombox.com/api/mcp/sse
Header: Authorization: Bearer kp_live_your_token_here

Option 3: Global Installation

npm install -g kroomboxpanel-mcp

# After global installation:
kroomboxpanel-mcp --url https://panel.kroombox.com --token kp_live_your_token_here

Client Configurations

Add kroomboxpanel-mcp to your favorite AI assistant in seconds:

1. Google Antigravity CLI (agy)

Add the server directly in your terminal using the native remote SSE command:

agy mcp add --header "Authorization: Bearer kp_live_your_token_here" kroomboxpanel-mcp https://panel.kroombox.com/api/mcp/sse

To verify the connection:

agy mcp list

2. Cursor IDE

Add to your project's .cursor/mcp.json (or user configuration):

Remote SSE (Zero-Footprint):

{
  "mcpServers": {
    "kroomboxpanel-mcp": {
      "url": "https://panel.kroombox.com/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer kp_live_your_token_here"
      }
    }
  }
}

Stdio via npx:

{
  "mcpServers": {
    "kroomboxpanel-mcp": {
      "command": "npx",
      "args": ["-y", "kroomboxpanel-mcp"],
      "env": {
        "KROOMBOXPANEL_URL": "https://panel.kroombox.com",
        "KROOMBOXPANEL_API_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

3. Claude Desktop

Add to claude_desktop_config.json (located in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows):

Direct Stdio CLI via npx (CLI Flags):

{
  "mcpServers": {
    "kroomboxpanel-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "kroomboxpanel-mcp",
        "--url",
        "https://panel.kroombox.com",
        "--token",
        "kp_live_your_token_here"
      ]
    }
  }
}

Alternative with Environment Variables:

{
  "mcpServers": {
    "kroomboxpanel-mcp": {
      "command": "npx",
      "args": ["-y", "kroomboxpanel-mcp"],
      "env": {
        "KROOMBOXPANEL_URL": "https://panel.kroombox.com",
        "KROOMBOXPANEL_API_TOKEN": "kp_live_your_token_here"
      }
    }
  }
}

4. Windsurf (Codeium)

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kroomboxpanel-mcp": {
      "serverUrl": "https://panel.kroombox.com/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer kp_live_your_token_here"
      }
    }
  }
}

5. Zed Editor

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "kroomboxpanel-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "kroomboxpanel-mcp",
          "--url",
          "https://panel.kroombox.com",
          "--token",
          "kp_live_your_token_here"
        ]
      }
    }
  }
}

Configuration & Environment Variables

The CLI client automatically detects settings from environment variables or command-line flags.

CLI Options

| Flag | Description | Default | |---|---|---| | --url <url> | Target Kroombox / KolabPanel base URL | http://127.0.0.1:5152 | | --token <token> | Scoped API Bearer Token (kp_live_... or kbx_live_...) | "" | | -h, --help | Display CLI usage help | | | -v, --version | Display version | |

Environment Variables

| Variable | Description | |---|---| | KROOMBOXPANEL_URL | Base URL of your panel instance (e.g. https://panel.kroombox.com) | | KROOMBOXPANEL_API_TOKEN | Bearer API token generated from your panel account | | KOLABPANEL_URL | Alias fallback for base URL | | KOLABPANEL_API_TOKEN | Alias fallback for API token |

Available MCP Tools (59 Tools Across 14 Modules)

The server exposes 59 structured tools designed for LLM function-calling:

1. Dashboard & Resource Metrics

• kroombox_get_dashboard_summary: Overview of account sites, databases, CPU/RAM utilization, and bandwidth.
• kroombox_get_resource_usage: Live real-time memory, disk, and load metrics.

2. Hosting: Sites & Process Management

• kroombox_list_sites: List all deployed applications, ports, root paths, and online statuses.
• kroombox_get_site_details: Retrieve deep configuration and environment details for a site.
• kroombox_manage_site_process: Control application lifecycle (start, stop, restart, reload).
• kroombox_get_site_logs: Fetch the latest runtime stdout and stderr logs for debugging.
• kroombox_delete_site: Permanently remove an application and cleanup vhosts.

3. Hosting: Domains & SSL Certificates

• kroombox_list_domains: List all active custom domains and DNS mapping.
• kroombox_add_custom_domain: Attach a new domain or subdomain to a site.
• kroombox_verify_domain_dns_ssl: Check DNS A/CNAME records and provision Let's Encrypt SSL.
• kroombox_remove_custom_domain: Detach custom domain from vhost.

4. Hosting: Databases

• kroombox_list_databases: List all MySQL databases, collations, and storage usage.
• kroombox_create_database: Provision a new isolated database and user credentials.
• kroombox_get_database_credentials: Retrieve connection host, port, username, and password.
• kroombox_export_database_backup: Trigger a SQL dump export.
• kroombox_delete_database: Drop database and revoke credentials.

5. Hosting: Terminal & Execution

• kroombox_execute_terminal_command: Execute non-destructive shell commands inside tenant jail.

6. File Manager

• kroombox_list_files: Browse directory contents, file sizes, and modification timestamps.
• kroombox_read_file_content: Read the content of configuration, source, or environment files.
• kroombox_write_file_content: Write or update file content safely.
• kroombox_create_file_or_folder: Create a new file or directory.
• kroombox_rename_file: Rename or move files.
• kroombox_copy_file: Duplicate files.
• kroombox_move_file: Move files across directories.
• kroombox_delete_file: Remove files or folders.

7. Git Version Control Operations

• kroombox_get_git_status: Inspect working directory state and uncommitted changes.
• kroombox_git_pull_latest: Pull updates from remote repository branch.
• kroombox_git_switch_branch: Checkout another branch.
• kroombox_git_view_commit_logs: Review commit history.
• kroombox_git_discard_changes: Revert uncommitted changes (git reset --hard).

8. Analytics & Health Monitoring

• kroombox_get_site_analytics: Visitor sessions, pageviews, and bounce rates.
• kroombox_get_traffic_breakdown: Geographic, browser, and device telemetry.
• kroombox_get_site_health: Uptime, response times, and HTTP status codes.

9. Deployment Wizard

• kroombox_analyze_source_blueprint: Inspect project repository to auto-detect framework and build scripts.
• kroombox_validate_deployment: Pre-flight check: verify quota, storage limits, database slots, framework permission, and subdomain availability without changing system state.
• kroombox_upload_site_archive: Stage or upload large project archives (>25MB) or local server paths in chunks.
• kroombox_deploy_new_site: Launch autonomous All-in-One deployment pipeline (Git, Base64 zip, local archive, or staging upload).
• kroombox_diagnose_site: Autonomous troubleshooting tool for diagnosing application crashes, PM2 errors, Auto-Recovery Limit Reached states, and port issues.
• kroombox_get_deployment_status: Poll build and deployment progress, step status, conclusion, and recent logs.

10. Additional Services & Integrations

• kroombox_list_active_services: Overview of background microservices.
• kroombox_get_ai_service_keys: View AI engine API keys.
• kroombox_create_ai_service_key: Generate new AI keys.
• kroombox_get_whatsapp_session_status: Check WhatsApp notification session.
• kroombox_restart_whatsapp_service: Restart gateway daemon.

11. Billing & Subscription Management

• kroombox_get_subscription_info: Active plan quota, expiration, and renewal info.
• kroombox_list_available_plans: Explore hosting tier plans and pricing.
• kroombox_list_invoices: View invoice transaction history.
• kroombox_create_payment_order: Generate checkout orders.

12. User Manual & Knowledge Base

• kroombox_search_user_manual: Search documentation, guides, and troubleshooting walkthroughs.
• kroombox_get_manual_topic: Retrieve complete guides by topic slug.

13. Customer Support & Tickets

• kroombox_list_tickets: List support inquiry tickets.
• kroombox_get_ticket_details: Read ticket messages and technician responses.
• kroombox_create_support_ticket: Open a new priority support ticket.
• kroombox_reply_support_ticket: Send follow-up replies to support team.

14. Profile & API Token Management

• kroombox_get_user_profile: Account username, email, and subscription level.
• kroombox_update_user_profile: Update account details.
• kroombox_list_api_tokens: List all active API tokens and permission scopes.
• kroombox_create_api_token: Create new scoped token for AI agents.
• kroombox_revoke_api_token: Revoke compromised or expired tokens.

Security & Permission Model

Every request executed by an AI agent must be authenticated with a fine-grained API Bearer Token (kp_live_... or kbx_live_...).

Tokens enforce wildcard-capable scopes:

| Token Scope | Granted Permissions | |---|---| | *:* | Full administrative control over all resources in the user account | | sites:* | Full read, deploy, reload, and management of all applications | | sites:read | Read-only inspection of site lists, configurations, and logs | | files:* | Read and write access to application files | | databases:* | Create, export, and delete databases | | terminal:exec | Ability to run shell commands |

Tenant Isolation: An AI assistant using kroomboxpanel-mcp is strictly isolated within the boundaries of the authenticated user's account and directories. It can never read other users' files or modify system-wide configurations.

Declarative MCP Resources

In addition to callable tools, kroomboxpanel-mcp implements official Model Context Protocol Declarative Resources (resources/list and resources/read), allowing AI clients to attach live panel state directly into their context window:

| Resource URI | MIME Type | Description | |---|---|---| | kroombox://user/quota | application/json | Active subscription plan, remaining site slots, database limits, and storage usage metrics. | | kroombox://sites | application/json | Catalog of tenant sites, framework engines, active ports, and health status. | | kroombox://sites/{site_id}/status | application/json | Deep operational status, runtime port, and live URLs for a specific site. | | kroombox://sites/{site_id}/logs/build | text/plain | Deployment pipeline build console logs and stderr traces. | | kroombox://sites/{site_id}/logs/runtime | text/plain | Live PM2 runtime console logs for Node.js / React backend applications. |

Backward Compatibility: Legacy kolab:// URI schemes (e.g. kolab://user/quota) are automatically normalized to kroombox://.

Tenant Sandboxing & Security Guardrails

The MCP execution engine operates behind automated security guardrails (server/utils/tenantSandbox.js):

1. Environment Sanitization: Strips dangerous injection variables (LD_PRELOAD, NODE_OPTIONS, BASH_ENV, PERL5LIB, etc.) when configuring tenant .env files.
2. Path Traversal Containment: Enforces strict directory boundaries with validateContainedPath to guarantee site assets cannot escape tenant roots (/volume1/web/Web/kolabpanel-v1/storage/{email}/).
3. Decoupled Architecture: All core deployment actions delegate to server/services/siteService.js, decoupling business logic from transport protocols (REST vs JSON-RPC vs SSE).

Conversational Prompts for AI Assistants

Once connected, your AI assistant can understand natural language hosting requests:

• "List all sites running in my account and show their PM2 process status."
• "Check the latest 100 lines of error logs for my backend API."
• "Deploy a new React application from GitHub repository https://github.com/myorg/web."
• "Create a new MySQL database named ecommerce_db and give me the credentials."
• "Pull the latest commits from branch main and restart the site without downtime."
• "Read .env.production file and update the database host address."
• "What is our server's current RAM and CPU utilization?"

Direct HTTP & SSE Endpoints

For custom agent developers or automated pipelines:

• GET /api/mcp/sse: Server-Sent Events stream initiation.
• POST /api/mcp/messages: SSE JSON-RPC message delivery.
• POST /api/mcp/rpc: Direct stateless JSON-RPC 2.0 endpoint.
• GET /api/mcp/tools: Machine-readable JSON catalog of all 56 tool schemas.
• GET /api/mcp/cli.js: Standalone lightweight Node.js CLI runner download.

License

Distributed under the MIT License. See LICENSE for more information.

Copyright © 2026 Kroombox Cloud Engineering. All rights reserved.