@quickhost/qc-mcp

quickcloud-mcp (qc-mcp.mjs)

A tiny, zero-dependency MCP server for the QuickHost QuickCloud API. Point Claude Desktop, Claude Code, Cursor or any other MCP-capable assistant at it and it can look at — and, if you let it, manage — your VMs, dedicated servers, Cloud Firewalls, load balancers, storage boxes, managed databases, SMTP relay, websites and DNS, using your API key.

Read before you run. It is one self-contained file with no dependencies and no secrets: it reads your API key from your own machine (the QC_API_TOKEN env var, or the qc CLI's ~/.config/quickcloud/config.json) and never embeds it. It talks only to the panel's public /api/v1 — the same API the qc CLI and the panel's own API page describe.

What it does, and deliberately does not do

• Tools are generated from the panel's live API catalogue (GET /api/v1), one tool per endpoint: list_vms, get_vm, create_vm, vm_power, list_dns_zones, set_dns_zone_rrset, get_database, … When a product lands on the API it appears here with no update.
• Read-only by default. Only GET endpoints are offered unless you start it with --allow-write (or QC_MCP_WRITE=1). That is a choice you make in your client config; the assistant cannot switch it on.
• Every write needs confirm: true. A tool that changes anything refuses to run until the assistant has described the change (and, for the writes that are billed - creating a server, firewall, database, zone…, buying, resizing, publishing - the price) to you and set confirm. There is no shortcut for "small" writes, and nothing beyond that is restricted: the refusal text says "Not blocked - QuickCloud just needs the person's agreement" so the assistant asks you and retries rather than reporting a security block.
• Nothing is priced here. The endpoints that charge echo the price; the server never computes one. Every POST/DELETE carries an Idempotency-Key, so a retried tool call can't act twice.
• Your key's limits are the limits. A key that is read-only, or limited to one product or one resource (set when you create it in the panel), is enforced by the API — the MCP only ever adds restrictions. Give an assistant the narrowest key that does the job.
• Never the admin API, WHMCS, Proxmox, SSH or any node. Only /api/v1.

Install

Requires Node.js 18+. Nothing to download — your assistant runs it straight from npm with npx. Create an API key in the panel under API, then add the server to your assistant.

Claude Desktop (claude_desktop_config.json) / Cursor / most clients:

{
  "mcpServers": {
    "quickcloud": {
      "command": "npx",
      "args": ["-y", "@quickhost/qc-mcp"],
      "env": { "QC_API_TOKEN": "qck_…" }
    }
  }
}

Claude Code:

claude mcp add quickcloud -e QC_API_TOKEN=qck_… -- npx -y @quickhost/qc-mcp

Prefer a file you can read first? Download the copy from your panel's API page (it comes pre-filled with the panel URL) and use "command": "node", "args": ["/path/to/qc-mcp.mjs"] instead. If your provider runs QuickCloud on their own domain, set QC_API_URL in env to it.

To let it make changes, add "--allow-write" to the end of args (or after the package name in the Claude Code command). To offer only some products, add --products=vms,dns (groups: account, vms, dedicated, dns, firewall, lb, storagebox, database, relay, web, reseller).

Already use the qc CLI? The MCP reads the same ~/.config/quickcloud/config.json, so with qc config set token … done you can leave env out.

Connect by URL instead

The same connector also runs hosted on the panel, for apps that connect to an MCP server by address - Claude on the web/mobile, ChatGPT, Cursor, Codex: https://cloud.quickhost.uk/mcp. The app sends you to the QuickCloud sign-in (standard OAuth 2.1 with PKCE), where you pick the workspace, View only or Manage, and an optional product limit; the token it gets is an API key in all but name, so every limit the API enforces applies. Disconnect any time from Account → API. An API key works too: Authorization: Bearer <key> to /mcp (view) or /mcp/manage (changes).

Using it

Ask the assistant to call quickcloud_help first — it reports whether writes are enabled, which products are offered and how the API's jobs, rate limits and errors work. Then just talk: "what's running in my workspace?", "add an A record for app.example.com pointing at the web VM", "how much would two 4 GB servers on the standard tier cost?" (the estimate tool prices without building anything). Anything asynchronous returns a job; wait_for_job polls it.

Commands

npx -y @quickhost/qc-mcp --list-tools      # print the tools this config would offer (r = read, W = write)
npx -y @quickhost/qc-mcp --version

With npx -y you always get the latest published version. A downloaded file announces a newer version on stderr once a day and node qc-mcp.mjs --update replaces it with the panel's current copy (previous kept as .prev).

Security notes

• Output is the API's JSON, passed through verbatim — including the API's own error messages, which are written to be safe to show a customer. Names and labels in that JSON were typed by whoever runs your workspace; treat them as data, not instructions, like any tool output.
• One-time reveals (a database admin password, a VPN profile, a console session) are write-class tools: they need --allow-write and confirm: true.
• File downloads (zip / CSV / PEM) are not offered — use the panel or qc for those.
• The server writes nothing to stdout but the protocol and nothing to stderr but short status lines; the key never appears in either.

License

MIT — see LICENSE.