CloudOps MCP Server

A unified cloud operations MCP (Model Context Protocol) server that gives AI Agents full-stack cloud operations capabilities.

One MCP Server manages both Alibaba Cloud + Tencent Cloud, covering server management, project deployment, database queries, file operations, cloud instance queries, DNS/CDN management — 6 major scenarios, 26 tools.

Version

• Current version: v1.0.0 (see CHANGELOG.md).

Related MCP server: Coolify MCP Tools

Documentation Navigation

• README.md (this file): Connector master document — tool list, one-click install (copy-paste to AI), manual install, configuration wizard, architecture, tool details, extension guide.

• OPERATIONS.md: Real-world operations Playbook (P1–P8), containing hands-on "goal + process" manuals for "obtaining keys / uploading SSH public keys / setting up NOPASSWD sudo / changing CDN origin server", etc. Check this first when you need to manually operate the cloud console.

• CHANGELOG.md: Version update history.

Tool Overview (26 tools)

One-Click Install (Copy-Paste to AI) ⭐ Recommended

The repository is public, so any AI tool that supports third-party MCP can clone and use it directly. Copy the following text verbatim to your AI assistant, and it will handle everything itself: clone → read docs → install dependencies → configure → register connector → verify all 26 tools. Works with mainstream Agents such as WorkBuddy, Hermes Agent, Claude Code, Codex CLI. Faster than manual install — use this first.

请帮我安装并学会使用 CloudOps MCP Server（统一云运维 MCP 连接器，GitHub: https://github.com/rowanlin-dev/cloud-ops-mcp）。

步骤：
1. 克隆仓库：git clone https://github.com/rowanlin-dev/cloud-ops-mcp.git && cd cloud-ops-mcp
2. 通读仓库内 README.md 与 OPERATIONS.md，掌握 26 个工具（server_exec / deploy_project / db_query / file_list / cloud_list_instances / dns_list_domains / cdn_refresh / cdn_task_status 等）的能力与用法
3. 安装依赖：npm install
4. 初始化配置：cp .env.example .env，然后引导我填写最小配置（至少一台 SSH 服务器：host / username / privateKey 或 password；云 AK、数据库等用到再填）
5. 按下方「各客户端注册方式」把我注册为 MCP 连接器
6. 验证：重启后应能列出 26 个工具，用 server_info 或 server_exec 测试连通

注意：.env 含云密钥、SSH 私钥路径等敏感信息，绝不可提交到 git（.gitignore 已排除）。

Registration Methods for Each Client

Replace <path> below with your actual clone path (e.g. E:/WorkSpace/cloud-ops-mcp, /home/user/cloud-ops-mcp). .env is auto-loaded based on the source path (not dependent on the process working directory), so none of the registration methods below require setting a working directory.

WorkBuddy (~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "cloud-ops": {
      "command": "npx",
      "args": ["tsx", "<路径>/cloud-ops-mcp/src/index.ts"],
      "cwd": "<路径>/cloud-ops-mcp"
    }
  }
}

Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  cloud-ops:
    command: "npx"
    args: ["tsx", "<路径>/cloud-ops-mcp/src/index.ts"]

Claude Code (one command; run after cd into the project directory or from within the project):

claude mcp add --transport stdio cloud-ops -- npx tsx <路径>/cloud-ops-mcp/src/index.ts

Codex CLI (~/.codex/config.toml):

[mcp_servers.cloud-ops]
command = "npx"
args = ["tsx", "<路径>/cloud-ops-mcp/src/index.ts"]

After registration, restart the corresponding AI client (or run its MCP reload command, e.g. Hermes' /reload-mcp) to see all 26 tools including server_exec, deploy_project, db_query, cdn_refresh, etc.

Manual Install (Quick Start)

The following are the manual install steps (clone → configure → register → verify). Want it faster? Use the "One-Click Install (Copy-Paste to AI)" above to let the AI do it automatically.

1. Clone & Install

git clone <your-repo-url> cloud-ops-mcp
cd cloud-ops-mcp
npm install

The project uses tsx as the TypeScript runtime — no compilation step needed.

2. Configuration

cp .env.example .env
# 编辑 .env 填入你的配置

Minimal configuration (SSH only):

SSH_HOST=your-server-ip
SSH_PORT=22
SSH_USER=root
SSH_PRIVATE_KEY=~/.ssh/id_rsa

See .env.example for the full list of configuration items, supporting multiple servers, databases, and Alibaba Cloud/Tencent Cloud AKs.

💡 Runtime server registration: Besides manually editing SSH_SERVERS in .env, you can also use the server_add tool to register at runtime (writes to .env and hot-updates the in-memory cache — no connector restart needed). See "Tool Details → server_add" below.

3. Register with an MCP Client (any AI tool that supports third-party MCP)

This connector is not WorkBuddy-exclusive. As long as your AI tool meets two requirements, you can use it:

1. Can install the kimi-webbridge skill (used as a fallback for console automation without a public API);

2. Supports installing third-party MCP connectors (stdio protocol). Common examples include WorkBuddy, Claude Desktop, Cursor, VS Code (Cline/Continue extensions), etc.

Generic registration snippet (replace /absolute/path/to/cloud-ops-mcp with your actual path):

{
  "mcpServers": {
    "cloud-ops": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/cloud-ops-mcp/src/index.ts"],
      "cwd": "/absolute/path/to/cloud-ops-mcp"
    }
  }
}

Configuration file locations for each client:

cwd must point to the project root — the MCP Server needs to load .env and node_modules from that directory. By default, the configuration wizard will not automatically rewrite any client's MCP configuration; if you want the wizard to write it automatically, you can set the environment variable CLOUD_OPS_MCP_CONFIG_PATH to point to the target configuration file path (optional).

4. Verification

# 测试阿里云工具
npx tsx src/test-aliyun.ts

# 测试 SSH 工具
npx tsx src/test-ssh.ts

# 直接启动 MCP Server（查看日志）
npx tsx src/index.ts

Configuration Wizard (Recommended)

The configuration wizard is a Web UI that lets you visually edit all of .env in your browser — it can both auto-fetch (via Kimi WebBridge scanning the cloud console) cloud instances and keys and backfill them, and let you manually fill in SSH private key paths, remote login passwords, database credentials, deployment defaults, and all other fields. Even users with zero experience can get started directly.

You can still manually edit the .env file at any time (see the manual playbook in OPERATIONS.md); the wizard is just a friendlier entry point, not the only way.

What Configuration to Prepare First (Required / Optional)

Only SSH servers are required; cloud AKs, databases, and deployment defaults are all "configure only when needed". For purely manual deployment (e.g. only server_exec + deploy_project), you can configure SSH only.

Prerequisites

• Kimi WebBridge browser automation daemon (npm run config will auto-detect / start / install it; you can also install it manually)

• The browser extension must be installed manually: https://www.kimi.com/zh-cn/features/webbridge

Kimi WebBridge's role: It is used for console operations that do not have a clean public API (e.g. QR-code login to cloud vendor consoles, reading AK/SK, some advanced CDN configurations). For capabilities that already have a public API (key configuration, CDN cache refresh, instance queries, etc.), tool automation is preferred; Kimi WebBridge is an "optional fallback when no API exists".

Usage Steps

# 1. 启动配置向导（会自动检测 / 启动 / 安装 Kimi WebBridge，无需手动先 start）
npm run config

# 2. 打开浏览器访问 http://localhost:3456
# 3. 点击「阿里云全自动配置」或「腾讯云全自动配置」
# 4. 扫码登录云控制台（唯一手动步骤）
# 5. 向导自动读取服务器实例（阿里云同时扫描 ECS + SWAS 轻量服务器，腾讯云扫描 CVM + Lighthouse）和 AK/SK
# 6. 点击「保存配置」完成

Kimi WebBridge auto-handling: npm run config will automatically detect the daemon — if it's already running, it uses it directly; if installed but not running, it starts it automatically; if not installed, it installs it automatically using the official command (Windows: irm https://cdn.kimi.com/webbridge/install.ps1 | iex; macOS/Linux: curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash) and then starts it. If automatic installation fails or you prefer to do it manually, just install it yourself using the commands above.

⚠️ The browser extension must be installed manually: The daemon can be installed automatically, but the browser extension (which lets the daemon take over your real browser session) cannot. Please install and log in manually at https://www.kimi.com/zh-cn/features/webbridge. WebBridge is only a fallback for "auto-fetching cloud AKs"; if it's not installed, the wizard can still fill in .env manually — it won't block you.

RAM Users (Recommended, Automatic)

Both Alibaba Cloud and Tencent Cloud show a confirmation dialog recommending RAM/sub-account keys instead of root account keys when "creating keys". The configuration wizard now detects this dialog and automatically switches to the sub-user flow:

1. Create a dedicated sub-user cloud-ops-mcp in the RAM/CAM console (check programmatic access);

2. Generate an AccessKey for this sub-user and read the KeyId/Secret;

3. Best-effort attach the minimal permission policies the connector needs (ECS/SWAS/Lighthouse read-only, CDN refresh, DNS resolution);

4. Write the sub-user key into .env — never the root account key.

If automatic policy attachment fails, the wizard generates a MANUAL_STEPS.md containing the minimal permission policy JSON you need to attach manually — just follow the steps to complete it. All console UI detection signals are configurable lists; on detection failure, it always degrades to manual steps and never mistakes "clicking through a dialog" for success.

Minimal permissions (full admin AdministratorAccess / QcloudAdministrator disabled): Alibaba Cloud AliyunECSReadOnlyAccess / AliyunSWASReadOnlyAccess / AliyunCDNFullAccess / AliyunDNSFullAccess; Tencent Cloud QcloudCVMReadOnlyAccess / QcloudLighthouseReadOnlyAccess / QcloudCDNFullAccess / QcloudDNSPodFullAccess.

Idempotent Behavior When Re-running the Wizard (Important)

The configuration wizard can be safely run repeatedly — it is idempotent against "re-creating AKs / re-creating sub-users":

1. Existing AKs are not re-fetched: When ALIBABA_CLOUD_ACCESS_KEY_ID already exists in .env, clicking "Alibaba Cloud Full Auto-Config" will keep the existing configuration by default, skip browser auto-fetch, and log "existing configuration kept". If you really want to re-fetch, click the "Re-fetch" button (which takes the forced refresh path).

2. RAM/CAM sub-users are automatically reused: The wizard always uses a sub-user named cloud-ops-mcp. On re-run, it first checks whether this sub-user already exists — if it exists, it reuses it and does not create it again (Alibaba Cloud's CreateUser errors out on duplicate names, which was exactly the pitfall of early repeated runs).

3. AccessKey rotation instead of accumulation: When reusing an existing sub-user, the wizard first cleans up the existing AccessKeys under that sub-user (best-effort), then creates a new pair and writes them to .env, avoiding hitting the 2-key limit or long-term accumulation.

4. Trail left for easy cleanup: Any RAM sub-user created/reused via the wizard gets an ALIYUN_RAM_USER=cloud-ops-mcp marker written into .env. To fully remove it later, just delete that sub-user in the Alibaba Cloud RAM console (make sure the connector no longer uses its keys before deleting).

In short: repeatedly clicking "Full Auto-Config" is safe — it either keeps, reuses, or rotates; it never spawns extra sub-users or keys out of thin air.

Shutting Down the Daemon After Configuration

# 1. 关闭配置向导（在运行 npm run config 的终端按 Ctrl+C）

# 2. 关闭 Kimi WebBridge 守护进程
# Windows PowerShell:
& "$env:USERPROFILE\.kimi-webbridge\bin\kimi-webbridge.exe" stop

# 验证已关闭（无输出或进程不存在即已停止）
& "$env:USERPROFILE\.kimi-webbridge\bin\kimi-webbridge.exe" status

The configuration wizard is optional. Manually editing the .env file always works (see the manual playbook in OPERATIONS.md).

Configuration Wizard API Endpoints

The wizard backend (Express) exposes the following endpoints for the frontend:

Full Auto-Config Flow (Summary)

• Alibaba Cloud: Open ECS console → detect/QR-code login → extract IPs and names from the instance list → jump to RAM "API Keys" → detect the "RAM user recommended" dialog and switch to the sub-user flow → get AK/SK → backfill the form.

• Tencent Cloud: Open CVM console → detect/QR-code login → extract instances → jump to CAM "API Keys" → detect the dialog and switch to the sub-user flow → get SecretId/Key → backfill the form.

The two clouds can be clicked separately; configurations are merged into the same .env.

Notes

1. Browser automation may need fine-tuning: Cloud console page structures change; when auto-extraction fails, a page preview is shown for troubleshooting.

2. SecretKey may not be auto-extractable: Some cloud platforms hide the Secret for security reasons; you'll need to copy-paste it manually in that case.

3. SSH key path: Auto-config defaults to ~/.ssh/id_rsa; if your path differs, modify it manually in the config preview (on Windows, an absolute path like /C:/Users/<LOCAL_USER>/.ssh/... is recommended).

4. Multi-cloud merging: You can click the Alibaba Cloud / Tencent Cloud buttons separately; both configurations merge into the same .env.

Architecture

AI Agent（任意支持 MCP 的客户端，如 Claude / Cursor / WorkBuddy）
        │
    MCP Protocol (stdio)
        │
CloudOps MCP Server (TypeScript + tsx)
   │       │       │       │       │       │
 server   deploy    db     file    cloud    dnscdn   ← 工具模块 (26 tools)
   │       │       │       │       │       │
   SSH    MySQL   Git   AliSDK  TcSDK   DNSPod/CDN SDK
   │       │       │       │       │       │
   Alibaba Cloud / Tencent Cloud                  ← 目标云平台
   (ECS, SWAS, CVM, Lighthouse, CDN, DNSPod)

Kimi WebBridge（可选）── 浏览器自动化，兜底无公开 API 的控制台操作

Project Structure

cloud-ops-mcp/
├── src/
│   ├── index.ts                 # MCP Server 主入口
│   ├── config.ts                # 配置加载（.env + 环境变量）+ 运行时 server_add
│   ├── types.ts                 # TypeScript 类型定义
│   ├── clients/
│   │   ├── ssh.ts               # SSH 客户端 (ssh2)
│   │   ├── aliyun.ts            # 阿里云客户端 (ECS + SWAS)
│   │   ├── tencent.ts           # 腾讯云客户端 (CVM + Lighthouse，整包命名空间)
│   │   ├── cdn.ts               # 腾讯云 CDN 客户端
│   │   └── dnspod.ts            # 腾讯云 DNSPod 客户端
│   ├── tools/
│   │   ├── server.ts            # 服务器管理 (exec/info/list/add)
│   │   ├── deploy.ts            # 项目部署
│   │   ├── database.ts          # 数据库
│   │   ├── file.ts              # 文件管理
│   │   ├── cloud.ts             # 云实例查询 (ECS/SWAS/CVM/Lighthouse)
│   │   └── dnscdn.ts            # DNSPod + CDN 管理
│   ├── utils/
│   │   └── logger.ts            # 日志
│   ├── config-wizard/           # 配置向导（可选，依赖 Kimi WebBridge）
│   │   ├── server.cjs           # 向导后端
│   │   └── web/                 # 向导前端
│   ├── test-aliyun.ts           # 阿里云工具测试
│   └── test-ssh.ts              # SSH 工具测试
├── .env.example                 # 配置模板
├── .gitignore
├── package.json
├── tsconfig.json
├── OPERATIONS.md                # 运维 Playbook（P1–P7 实操手册）
└── README.md                    # 项目总文档（本文件）

Tool Details

server_exec — Remote Command Execution

参数: server(服务器名), command(命令), cwd(可选), timeout(可选, 默认60s, 最大600s)
超时: 默认 60 秒；构建/部署等长命令请显式加大 timeout；超时错误会附带提示
示例: 在 Tencent-LH 服务器上执行 docker ps

server_add — Runtime SSH Server Registration

参数: name, host, port(默认22), username, privateKey(可选), password(可选)
行为: 写入 .env 的 SSH_SERVERS 并热更新内存缓存，无需重启连接器即可被 server_exec 使用
示例: server_add(name="Tencent-LH", host="<LIGHTHOUSE_PUBLIC_IP>", port=22, username="<SSH_USER>", privateKey="C:/Users/xxx/.ssh/id_ed25519")
注意: 特权写文件请用 `echo x | sudo tee file`，勿用 `sudo cmd > file`（重定向由非 sudo shell 执行会 Permission denied）

deploy_project — Project Deployment

参数: server, projectPath, method(git-pull|upload|docker|script), branch, scriptCommand, buildCommand, restartCommand
示例: 将 /data/www/myapp 拉取最新代码并重启
script 方式: method="script", scriptCommand="bash /tmp/deploy_backend.sh" —— 在 projectPath 下执行自定义部署脚本
           （适合「备份→停服→换包→启服」这类现成脚本化流程，执行超时 5 分钟）

db_query — Database Query

参数: database(配置名), query(SQL), maxRows(默认100)
安全: 自动阻止 DROP/TRUNCATE/ALTER 等危险操作

file_read / file_write / file_search — File Operations

file_read:   读取远程文件内容（支持 tail 模式用于日志）
file_write:  写入内容到远程文件（建议配合 sudo tee 使用）
file_search: 用 grep 搜索文件内容

cloud_list_instances — Cloud Instance List

参数: provider(aliyun|tencent|all, 默认all)
支持:
  - 阿里云 ECS + SWAS(轻量应用服务器)   ← SWAS 自动扫描多个区域
  - 腾讯云 CVM(云服务器) + Lighthouse(轻量应用服务器)

cdn_refresh — CDN Cache Refresh (automated, no console needed)

参数: urls(URL/目录列表), type(url|path)
示例: cdn_refresh(urls=["https://<YOUR_DOMAIN>/","https://<YOUR_DOMAIN>/index.html"], type="url")
注意: type=path 时每个目录路径必须以 / 结尾（如 https://<YOUR_DOMAIN>/assets/），否则校验失败

cdn_task_status — CDN Refresh Task Progress Query (new in v1.0.0)

参数: taskId(可选，cdn_refresh 返回的任务ID), limit(默认10)
示例: cdn_task_status(taskId="<TASK_ID>") —— 查询任务是否 done/process/fail
用途: 刷新后轮询任务状态，替代「等 60 秒盲查 CDN」；留空可查最近记录

For more "goal + process" style manual operation instructions (obtaining keys, uploading SSH public keys, setting up NOPASSWD sudo, changing the CDN primary origin server, etc.), see OPERATIONS.md.

Common Usage Scenarios

The following are typical flows where an AI Agent drives the connector through natural language:

• Check server status: "Check the CPU and memory of Tencent-LH" → server_info → table display.

• Deploy a project: "Deploy myapp to Tencent-LH" → deploy_project (SSH pulls latest code → build → restart).

• Query a database: "Query the first 10 rows of the user table in prod-db" → db_query (connects via SSH tunnel, automatically blocks dangerous SQL).

• Manage cloud resources: "List all Lighthouse instances in Tencent Cloud Guangzhou region" → cloud_list_instances tencent.

• Refresh CDN: "Refresh the cache for <YOUR_DOMAIN>" → cdn_refresh.

Supported Cloud Platforms

The Tencent Cloud SDK uses the full tencentcloud-sdk-nodejs package and is accessed by namespace (cvm / lighthouse), avoiding "Cannot find module" errors caused by importing product subpackages that are not installed. Both the full package and the per-product subpackages are placed in optionalDependencies, so not installing them does not affect other functionality.

Operations Philosophy: Automation First, Manual Operations Have a Playbook

The connector's design boundaries (defined by owner):

1. Operate Alibaba Cloud/Tencent Cloud public APIs — for anything with a clean API (key configuration, CDN purge, instance queries, DNS resolution), prefer automating with tools.

2. Connect to cloud servers via SSH and run commands — server_add to register + server_exec for remote execution.

3. (Optional) Invoke Kimi WebBridge browser automation — for console operations that have no public API (QR-code login, reading AK/SK, some advanced CDN settings).

4. When users must operate manually, provide a "target + procedure" description — for capabilities that lack an API, the connector produces standard steps and a person executes them in the console.

The specific playbooks (including commands, console paths, and known pitfalls) are maintained centrally in OPERATIONS.md.

Security Features

• SSH key authentication is preferred over passwords

• Database queries automatically block dangerous operations (DROP/TRUNCATE/ALTER)

• All sensitive configuration (cloud AK, SSH private key path) is managed via .env, and .env is excluded in .gitignore; keep the actual SSH private key in your own secure location (e.g. ~/.ssh/), reference it by path through the privateKey field, and do not include it in the project directory

• SQL injection protection (parameterized queries, limited result set size)

• Command execution timeout mechanism (60s by default, up to 10 minutes, adjustable)

• CDN purge target input validation (URL must start with http(s)://; directory purge path must end with /)

• server_add performs a same-name check when writing to .env, preventing overwriting of existing servers

• It is recommended to set .env permissions to user-only read/write (chmod 600 .env)

• Rotate cloud service AK/keys regularly; create a dedicated cloud sub-account for the connector and follow least privilege (see "Configuration Guide → RAM User" above)

Extension Guide

Adding New Tools

1. Create a new module under src/tools/

2. Export a registerXxxTools(server: McpServer) function

3. Register it in src/index.ts

Adding a New Cloud Platform / Product

1. Create or extend SDK wrappers under src/clients/ (prefer reusing namespaces from the full tencentcloud-sdk-nodejs package)

2. Add the configuration type in src/config.ts

3. Add the tool in src/tools/cloud.ts

License

MIT