qc-mcp

quickcloud-mcp (qc-mcp.mjs)

一个为 QuickHost QuickCloud API 提供服务的微型零依赖MCP 服务。让 Claude Desktop、Claude Code、Cursor 或任何兼容 MCP 的助手连接到它，就可以查看你的虚拟机、专用服务器、Cloud Firewalls、负载均衡器、存储箱、托管数据库、SMTP 中继、网站和 DNS；如果你允许，还可以管理它们。使用的是你的 API 密钥。

运行前请阅读。 这是一个独立的单文件程序，没有依赖，也不含任何密钥：它会从你的设备读取 API 密钥（通过 QC_API_TOKEN 环境变量，或 qc CLI 的 ~/.config/quickcloud/config.json），绝不会将密钥嵌入其中。它只与面板公开的 /api/v1 通信——这也是 qc CLI 和面板 API 页面所介绍的同一套 API。

它会做什么，以及明确不会做什么

• 工具由面板的实时 API 目录生成（GET /api/v1），每个端点对应一个工具：list_vms、get_vm、create_vm、vm_power、list_dns_zones、set_dns_zone_rrset、get_database……产品一旦接入 API，就会自动出现在这里，无需更新。
• 默认只读。 除非使用 --allow-write（或 QC_MCP_WRITE=1）启动，否则只会提供 GET 端点。这是你在客户端配置中做出的选择；助手无法自行启用写入权限。
• 每次写入都需要 confirm: true。 任何会更改内容的工具都必须等助手向你说明更改内容（以及 API 报价的任何费用）并设置 confirm 后，才会执行。“小型”写入也没有捷径。
• 这里不会计算费用。 会产生费用的端点会返回价格；服务本身绝不会计算费用。每个 POST/DELETE 请求都会携带 Idempotency-Key，因此重试工具调用不会导致重复操作。
• 密钥的权限就是实际权限。 API 会强制执行密钥的限制，包括只读权限，或仅限某个产品或某项资源的权限（在面板中创建密钥时设置）——MCP 只会进一步限制权限。请为助手提供完成任务所需的最小权限密钥。
• 绝不访问管理 API、WHMCS、Proxmox、SSH 或任何节点。只访问 /api/v1。

安装

需要 Node.js 18+。无需下载任何内容——助手会通过 npx 直接运行。请在面板的 API 页面创建 API 密钥，然后将服务添加到助手中。

Claude Desktop（claude_desktop_config.json）/ Cursor / 大多数客户端：

{
  "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

想先阅读文件再使用？从面板的 API 页面下载副本（其中已预填面板 URL），然后改用 "command": "node", "args": ["/path/to/qc-mcp.mjs"]。如果你的服务提供商在自己的域名上运行 QuickCloud，请在 env 中将 QC_API_URL 设为该域名。

要允许它进行更改，请在 args 末尾添加 "--allow-write"（或在 Claude Code 命令中添加到包名之后）。要仅提供部分产品的工具，请添加 --products=vms,dns（分组：account、vms、dedicated、dns、firewall、lb、storagebox、database、relay、web、reseller）。

已经在使用 qc CLI？MCP 会读取同一个 ~/.config/quickcloud/config.json，因此运行 qc config set token … 设置好密钥后，就可以不配置 env。

改为通过 URL 连接

同一个连接器也托管在面板上，供通过地址连接 MCP 服务的应用使用——Claude 网页版/移动版、ChatGPT、Cursor、Codex：https://cloud.quickhost.uk/mcp。应用会将你引导至 QuickCloud 登录页面（采用标准 OAuth 2.1 和 PKCE），你可以在其中选择工作区、只读或管理权限，以及可选的产品限制；应用获得的令牌本质上就是 API 密钥，因此 API 强制执行的所有限制同样适用。你可以随时前往 Account → API 断开连接。也可以使用 API 密钥：向 /mcp（只读）或 /mcp/manage（更改）发送 Authorization: Bearer <key>。

使用方法

先让助手调用 quickcloud_help——它会报告是否已启用写入、提供哪些产品，以及 API 的任务、速率限制和错误如何运作。然后直接提问： “我的工作区里正在运行什么？”、“添加一条 A 记录，将 app.example.com 指向 Web 虚拟机”， “标准层级的两台 4 GB 服务的费用是多少？”（estimate 工具只计算价格，不会创建任何内容）。任何异步操作都会返回一个任务；wait_for_job 会轮询该任务。

命令

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

使用 npx -y 始终会获取最新发布的版本。已下载的文件每天会在 stderr 上提示有新版本，运行 node qc-mcp.mjs --update 会将其替换为控制面板中的当前版本（之前的版本会保留为 .prev）。

安全说明

• 输出是 API 的 JSON，原样传递——包括 API 自身的错误消息，这些消息经过编写，可安全地展示给客户。该 JSON 中的名称和标签由运行工作区的人员输入；应将其视为数据而非指令，就像任何工具输出一样。
• 一次性信息披露（数据库管理员密码、VPN 配置文件、控制台会话）属于写入类工具：需要 --allow-write 和 confirm: true。
• 不提供文件下载（zip / CSV / PEM）——请使用控制面板或 qc。
• 除协议内容外，服务不会向 stdout 写入任何内容；除简短状态行外，也不会向 stderr 写入任何内容；密钥不会出现在两者之中。

许可证

MIT — 详见 LICENSE。