colorfulbox-mcp

MCP server for ColorfulBox cPanel hosting. Operate domains, DNS, SSL, email, FTP, MySQL, PHP, cron, subdomains, WordPress (Installatron) detection and JetBackup listing from AI agents such as Claude Code, Cursor, Gemini CLI, Cline, Codex, Claude Desktop and VS Code.

Status: v0.12.0 — Phase 1 preview

What this version does: cPanel operations — domains, DNS records on the cPanel server, SSL, email, FTP, MySQL, PHP, cron, subdomains, plus read-only detection of Installatron applications and JetBackup backups.

New: WordPress management — list the sites on an account, back one up, update it, and restore a backup if the update went badly. Installatron cannot be reached with a cPanel API token, so these tools run through an operator-side gateway and are inert unless it is configured; a customer is never asked for a password. See §"WordPress management" below.

New: billing, read-only — what is outstanding, which invoices are open, what each service costs and when it renews. Amounts are repeated exactly as WHMCS records them, with tax broken out, and the account is fixed by configuration so no prompt can point these at another customer.

New: ordering and plan changes. These place a charge and cannot be undone here. A plan change is priced by WHMCS itself before you confirm, so the amount shown is the amount billed; a new order quotes the catalogue price and says plainly that promotions and options can change the invoice. The parameters that would override a price or suppress the customer's invoice and emails are not exposed at all.

What it does not do yet: paying or refunding anything, domain registration, and WordPress installation, cloning and migration. Those are planned for a later version — see docs/compatibility.md for the reserved namespaces they will use.

This is a preview released ahead of its documentation and announcement. Interfaces are stable (see the compatibility note above), but please expect the surface to grow. A companion agent skill lives in SKILL.md.

What it is

A thin, safety-first wrapper over cPanel's UAPI (primary) and API 2 (fallback, for cron / subdomains / SSH which have no UAPI). It runs locally over MCP stdio and talks directly to your cPanel server on port 2083 using a cPanel API token — no gateway, no server-side install.

Design principles:

• Read-first, preview → confirm with single-use token → change. Every mutating tool returns a preview (changing nothing) that issues a single-use confirmToken; execution requires re-calling with the same arguments plus confirm: true and that token. A lone confirm: true on the first call never executes — the two-step gate is enforced server-side. Tokens are bound to the exact tool+arguments and expire after ~5 minutes. This gate prevents accidental single-call execution; it is not by itself a human-approval boundary (the model can obtain and redeem the token).
• Human approval for high-risk operations (fail closed). Deletes, cron_add, and credential/forwarder creation additionally require a host-UI confirmation via MCP elicitation right before execution. On clients that do not support elicitation, these high-risk operations are refused by default (reads and previews still work). Trusted automation can opt back in with COLORFULBOX_ALLOW_UNATTENDED_WRITES=true. Do not enable your AI client's auto-approve mode — the host confirmation is the real human checkpoint.
• Secrets never leak. The API token and passwords are sent only in the auth header, and every log line / error / result is passed through redaction.
• One account, one server. A connection is bound to a single cPanel account; there is no cross-account addressing.
• Graceful degradation. Plan-gated or version-dependent features (Installatron, JetBackup, SSH) report unavailability instead of crashing.
• Stable public contract. Tool names/params are frozen at GA; future ordering/billing/provisioning tools live in reserved namespaces (order_*, billing_*, account_*) so upgrades are purely additive. See docs/compatibility.md.

Requirements

• Node.js 20+
• A ColorfulBox cPanel account and a cPanel API token (cPanel → Manage API Tokens). See docs/setup.md.

Configuration

Set via environment variables:

| Variable | Required | Description | |---|---|---| | COLORFULBOX_SERVER | ✅ | cPanel host, e.g. YOUR_CPANEL_HOST.cbsv.jp | | COLORFULBOX_API_TOKEN | ✅ | cPanel API token (secret) | | COLORFULBOX_CPANEL_USER | ✅ | cPanel username — required to authenticate (see note) | | COLORFULBOX_PORT | | cPanel port (default 2083) | | COLORFULBOX_TIMEOUT_MS | | per-request timeout (default 30000) | | COLORFULBOX_MAX_RETRIES | | retries on 429/5xx for reads only (default 2) | | COLORFULBOX_ALLOW_UNATTENDED_WRITES | | true lets high-risk ops (deletes, cron_add, credential/forwarder creation) run on clients without elicitation. Default false = fail closed. Only for trusted automation. | | COLORFULBOX_LOG_LEVEL | | debug\|info\|warn\|error\|silent (default info) | | COLORFULBOX_SSH_KEY_PATH | | Private key path — enables the SSH read-only path for WordPress/backup (see note) | | COLORFULBOX_SSH_HOST | | SSH host (default = COLORFULBOX_SERVER) | | COLORFULBOX_SSH_USER | | SSH user (default = COLORFULBOX_CPANEL_USER) | | COLORFULBOX_SSH_PORT | | SSH port (default 22) |

Operator-only — these enable the WordPress management tools. All five are required together. The credential behind them can open any account on the platform, so it belongs to whoever runs the server, never in a customer's client config:

| Variable | Description | |---|---| | COLORFULBOX_GATEWAY_WHMCS_URL | WHMCS API endpoint (https://…/includes/api.php) | | COLORFULBOX_GATEWAY_IDENTIFIER | WHMCS API credential identifier | | COLORFULBOX_GATEWAY_SECRET | WHMCS API credential secret | | COLORFULBOX_GATEWAY_CLIENT_ID | Client the session is minted for | | COLORFULBOX_GATEWAY_SERVICE_ID | Service (hosting account) the session targets |

WordPress detection and backup listing require the SSH read-only path. The cPanel API token cannot reach Installatron (HTTP 403) or JetBackup (no UAPI module) — both confirmed at runtime. Set COLORFULBOX_SSH_KEY_PATH (a private key whose public key is registered in cPanel → SSH Access) to enable wordpress_list and backup_list; without it they return available: false. Only a fixed allow-list of read-only commands runs over SSH — there is no arbitrary-command tool. This is a Phase-1 stopgap; Phase 2 replaces it with a gateway/SSO path.

The cPanel username is NOT your ColorfulBox mypage login. It is required to authenticate. Find it in cPanel (top-right), or as the main FTP account home directory /home/<username>. After connecting, server_whoami confirms it.

Quick start (Claude Code)

Keep the token out of your shell history and process list — read it into an environment variable first, then reference it (don't paste the literal token on the command line):

read -r -s COLORFULBOX_API_TOKEN && export COLORFULBOX_API_TOKEN   # paste token at the silent prompt
claude mcp add colorfulbox \
  -e COLORFULBOX_SERVER=YOUR_CPANEL_HOST.cbsv.jp \
  -e COLORFULBOX_CPANEL_USER=youruser \
  -e COLORFULBOX_API_TOKEN \
  -- npx -y colorfulbox-mcp

Passing -e COLORFULBOX_API_TOKEN (no =value) forwards it from the exported environment, so the secret never appears in the command itself. Avoid -e COLORFULBOX_API_TOKEN=<token> and avoid committing a JSON config that contains the literal token.

Then ask: "Confirm which ColorfulBox account I'm connected to and list my databases."

Client configuration

{
  "mcpServers": {
    "colorfulbox": {
      "command": "npx",
      "args": ["-y", "colorfulbox-mcp"],
      "env": {
        "COLORFULBOX_SERVER": "YOUR_CPANEL_HOST.cbsv.jp",
        "COLORFULBOX_CPANEL_USER": "youruser",
        "COLORFULBOX_API_TOKEN": "your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "colorfulbox": {
      "command": "npx",
      "args": ["-y", "colorfulbox-mcp"],
      "env": {
        "COLORFULBOX_SERVER": "YOUR_CPANEL_HOST.cbsv.jp",
        "COLORFULBOX_CPANEL_USER": "youruser",
        "COLORFULBOX_API_TOKEN": "your_token"
      }
    }
  }
}

See docs/setup.md for token issuance and full per-client steps.

Tools

Full per-tool reference (parameters, transports, error codes, examples): docs/tools.md

| Category | Tools | |---|---| | server | server_whoami, server_get_info, server_get_usage, server_list_api_tokens | | domain | domain_list, domain_list_details, domain_get | | subdomain | subdomain_list, subdomain_add, subdomain_delete† | | dns | dns_get_cpanel_zone, dns_lookup — cPanel-local scope; authoritative DNS is the ColorfulBox DNS Manager | | ssl | ssl_list_certs, ssl_list_installed, ssl_autossl_status | | mail | mail_list_accounts, mail_list_forwarders, mail_list_autoresponders, mail_add_account, mail_delete_account†, mail_add_forwarder* | | ftp | ftp_list, ftp_add, ftp_delete† | | mysql | mysql_list_databases, mysql_list_users, mysql_create_database, mysql_delete_database†, mysql_create_user, mysql_delete_user† | | php | php_get_versions | | cron | cron_list, cron_add, cron_remove† | | ssh | ssh_list_keys | | logs | logs_last_visitors | | wordpress | wordpress_list — WordPress detection (SSH read-only path; see note above) | | backup | backup_list — JetBackup listing (SSH read-only path; see note above) |

* write (preview → confirm: true + single-use confirmToken) · † destructive (same two-step gate + host elicitation where supported)

Security

• The cPanel user API token is full access and bypasses 2FA. Always set an expiry date and rotate it if exposed. Note: cPanel user-level tokens support only name + expiry — there is no IP whitelist and no per-feature scoping (those exist only for WHM/root tokens).
• Mutating operations are gated by a server-enforced two-step confirmation: the preview issues a single-use confirmToken (bound to the exact tool+arguments, ~5-minute TTL), and execution requires confirm: true together with that token. confirm: true alone never executes.
• Destructive tools (and cron_add) add an MCP elicitation confirmation through the host UI when the client supports it; an elicitation failure counts as a decline (fail closed).
• Residual risk, stated plainly: under a fully auto-approving client configuration, the host approval UI / elicitation prompt is the last line of defence for destructive changes. Keep a human in that loop.
• Structured tool output is wrapped in [UNTRUSTED DATA] … [END UNTRUSTED DATA] delimiters: cPanel responses can contain third-party-controlled strings, and agents must treat them as data, never as instructions (labelling only — no content is removed).
• The token/passwords are never logged, echoed, or returned.
• See SKILL.md for the operational norms agents should follow.

Development

npm install
npm run build      # tsc -> dist/
npm test           # vitest (mocked HTTP; no network)
node scripts/list-tools.mjs          # list registered tools (dummy creds)
node scripts/real-probe.mjs          # read probe against a live account (env creds)
node scripts/real-probe.mjs --write  # + a temporary-DB write/cleanup probe

Roadmap

• Next: gated write coverage (SSL install, JetBackup actions, SSH key import), 5-client live QA, security review. (DNS zone edits are deliberately not on this list: editing the cPanel-local zone would change a copy, not what the internet resolves. DNS writes belong to the authoritative layer — account_dns_* in Phase 2.)
• Phase 2: API gateway with scoped tokens, remote MCP (Streamable HTTP / OAuth for claude.ai / ChatGPT web), WHMCS ordering/billing (order_*, billing_*), WHM provisioning (account_*) and authoritative DNS via the ColorfulBox DNS Manager (account_dns_*) per docs/compatibility.md.

License

MIT © ColorfulLab, Inc.