CloudOps MCP Server

Unified cloud operations MCP (Model Context Protocol) server that gives AI agents full-stack cloud operations capabilities.

One MCP Server manages Alibaba Cloud + Tencent Cloud at the same time, covering 6 major scenarios: server management, project deployment, database querying, file operations, cloud instance query, DNS/CDN management — with 26 tools.

Version

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

Related MCP server: Coolify MCP Tools

Documentation Navigation

• README.md (this file): The connector's master document — tool list, one-click installation (copy & paste to AI), manual installation, configuration wizard, architecture, tool details, extension guide.

• OPERATIONS.md: Real-world operations playbook (P1–P8) that collects "goal + flow" runbooks such as "get credentials / upload SSH public key / set up NOPASSWD sudo / change CDN origin". Check this first when you need to manually operate a cloud console.

• CHANGELOG.md: Version release history.

Tool Overview (26 Tools)

One-Click Installation (copy and 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 text below as-is to your AI assistant, the assistant will do everything itself: clone → read docs → install dependencies → configure → register the connector → verify 26 tools. Works with mainstream agents such as WorkBuddy, ClickUp Agent, Claude Code, Codex CLI. Faster than manual installation — 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 已排除）。

Ways to register on each client

Replace the <path> below with your actual clone path (for example E:/WorkSpace/cloud-ops-mcp, /home/user/cloud-ops-mcp). .env is loaded automatically according to the source path (not dependent on the working directory of the process), so the following registration methods do not require a separate 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 — you need to either cd into the project folder or run it inside 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 AI client (or run its MCP reload command, such as Hermes /reload-mcp) and you will see the 26 tools including server_exec, deploy_project, db_query, cdn_refresh, and others.

Manual Installation (Quick start)

The following are the manual installation steps (clone → configure → register → verify). Want the faster route? Use the "One-Click Installation (copy and paste to AI)" above and 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]( https is automatically installed as the TypeScript runtime etc.; no compile step required.

2. Configure

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

For full options, see .env.example. Multiple servers, databases, and Alibaba Cloud/Tencent Cloud AK are supported.

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

3. Register to the MCP client (any AI tool that supports third-party MCP)

This connector is not WorkBuddy-only. Any AI tool will work as long as it supports two things:

1. the ability to install the kimi-webbridge skill (for fallback console automation for consoles without clean public API);

2. the ability to install third-party MCP connector (stdio protocol). Common options include WorkBuddy, Claude Desktop, Cursor, VS Code (Cline/Continue extensions), etc.

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

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

Config file locations for each client:

G> The cwd must point to the project root, because the MCP Server needs to load .env and node_modules from that directory. By default the Configuration Wizard does not rewrite any client's MCP config; if you want the wizard to write it automatically, set the environment variable CLOUD_OPS_MCP_CONFIG_PATH to the target config file path (optional).

4. Verify

# 测试阿里云工具
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 the whole .env in the browser. It can both automatically fetch (via Kimi WebBridge scanning the cloud console) cloud instances and credentials, and manually fill all fields such as SSH private-key path, remote login password, database credentials, deployment defaults, etc. Users with zero background can still get started comfortably.

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

Which config do you need to have (required / optional)

Only SSH servers is required; cloud API keys, databases, deployment defaults are config-on-use. For a purely manual SSH-only workflow (e.g. using only server_exec + deploy_project) you can configure only the SSH server.

Prerequisites

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

• Browser extension must be installed manually: https://www.kimi.com/zh-cn/features/webbridge (need to manually install from the official page)

What is Kimi WebBridge? it is used for the console operations that have no clean public API (for example, logging in by scanning a QR code into the cloud vendor console, reading AK/SK, some advanced CDN config). For things that already have a public API (credential config, CDN cache refresh, instance queries, etc.), automatic tools are preferred; Kimi WebBridge is just 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 automatically detects the daemon — if already running, it uses it; if installed but not running, it starts it; if not installed, it installs it automatically by 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 automated installation fails or you prefer to install it manually, just use the commands above.

⚠️ The browser extension must be manually installed: the daemon can be installed automatically, but the browser extension (the part that takes over your real browser session) cannot. You need to install and log in manually from https://www.kimi.com/zh-cn/features/webbridge. WebBridge is only used as fallback etc. to auto-fetch cloud AK/SK; if it is not installed, the wizard still works for manual .env editing; it does not block you.

RAM users (recommended, automatic)

the abilities the cloud providers prompt you when creating credentials: both Alibaba Cloud and Tencent Cloud show a confirmation box advising you to use a RAM/sub-user Account rather than the main account key. The Configuration Wizard now recognises this prompt and auto-switches to the sub-user flow:

1. Create a dedicated sub-user cloud-ops-mcp inside the RAM/GDPR console (with programmatic access).

2. Generate an AccessKey for this sub-user, read KeyId/Secret.

3. Try to attach the minimal privileges the plugin requires (ECS/SWAS/Lighthouse read-only, CDN purge, DNS manage records).

4. Write the sub-user credential into .env, never the main account credential.

If the automatic policy attach fails, the wizard generates MANUAL_STEPS.md, containing the least-privileged policy JSON that you need to attach manually — complete it as instructed. All console UI detection signals are configurable lists false detection. In case of a detection failure, it defaults back to manual steps rather than treating the “clicked/created” as success.

Least privilege (not require full admin AdministratorAccess / QcloudAdministrator): for Alibaba Cloud use AliyunECSReadOnlyAccess / AliyunSWASReadOnlyAccess / AliyunCDNFullAccess / AliyunDNSFullAccess; for Tencent Cloud use QcloudCVMReadOnlyAccess / QcloudLighthouseReadOnlyAccess / QcloudCDNFullAccess / QcloudDNSPodFullAccess.

Idempotence when re-running the wizard (important)

The Configuration Wizard is safe to run repeatedly — it contains idempotence logic against “wrongAK / unused sub-user” and so on.

1. Existing AKs will not be regenerated: if you already have ALIBABA_CLOUD_ACCESS_KEY_ID in .env, clicking “Alibaba Cloud auto config” will by default keep the existing configuration, skip the browser fetch, and log "already exists retained". If you really need to re-fetch, click the “Re-fetch” button (forced refresh).

2. RAM/CAM sub-user auto reuse: the wizard always uses a sub-user named exactly cloud-ops-mcp. On a re-run it first checks whether that sub-user already exists — if so, it reuses it without creating another (Alibaba Cloud's CreateUser will directly return a duplicate name error, which is exactly the pain point of repeated runs).

3. AccessKey rotation rather than accumulation: when re-using an existing sub-user, the wizard first cleans up any existing AccessKeys under that sub-user (best-effort), then creates a new one and writes it into .env, avoiding exceeding the quota of 2, or accumulating stale keys.

4. Trace via a marker: If a RAM/CAM user was created/reused by the wizard, it will write ALIYUN_RAM_USER=cloud-ops-mcp into .env. To later completely remove it, delete the sub-user in the Alibaba RAM console (ensure not being used by this plugin anymore first).

In a nutshell: hitting “Auto-Config” repeatedly is safe — it either keeps, reuses, or rotates; it never creates extra sub-users or keys.

After configuration: stop the daemon

# 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. You can always edit the .env file manually (see the manual playbook in OPERATIONS.md).

Configuration Wizard API

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

The full auto-flow (brief):

• Alibaba Cloud: opens the ECS console → detects the login/s scan QR → extracts instance IP and name from the console list → goes to RAM API Keys → detects the “RAM user” popup and switches to the sub-user flow → obtains AK/SK → fills the form. Tencent Cloud: opens the CVM console → detects login / scans QR → extracts instances → goes to Tencent Cloud CAM API Keys → detects the popup and switches to the sub-user flow → obtains SecretId/Key → fills the form.

You can click the two clouds separately, the config will be merged into the same .env.

Notes

1. Browser automation may need fine-tuning: cloud console page structures change. If auto-extraction fails, a page preview is shown for investigation.

2. SecretKey may not be auto-extractable: some cloud security policies hide the Secret; in that case paste it manually.

3. SSH key path: defaults to ~/.ssh/id_rsa in auto config; if you use a different path, change it in the preview (Windows users are advised to use an absolute path like /C:/Users/<LOCAL_USER>/.ssh/...).

4. Multi-cloud merging: you can click Alibaba Cloud / Tencent Cloud buttons separately; both configurations are merged 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 — Register SSH server at runtime

参数: 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 status query (new in v1.0.0)

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

More detailed "goal + actions" manual operation guides (obtaining keys, uploading SSH public key, establishing NOPASSWD sudo, CDN origin changes, etc.) are in OPERATIONS.md.

Common Usage Scenarios

The following examples show how a natural-language AI agent can drive the adapter:

• Check server status — “Check the CPU and memory of Tencent-LH” → server_info → display the stage/agent.

• Deploy a project — “Deploy myapp to Tencent-LH” → deploy_project (SSH pulls the latest code → build → restart).

• Query a database — “Query the top 10 rows of the user table in prod-db” → db_query (via SSH tunnel connected to the database, dangerous SQL are intercepted automatically).

• Manage cloud resources — “List all Lighthouse instances in Tencent Cloud Guangzhou” → cloud_list_instances tencent.

• Refresh CDN — “Refresh cache for <YOUR_DOMAIN>” → cdn_refresh.

Supported Clouds

Wait, there is a trailing "## 支持的云平台" but no content in the source. We should not add any invented content. Only output the heading, but it feels incomplete. The user said input may be section of a longer doc, translate as given. So end with "## Supported Cloud Platforms" (if that heading appears at end). The input's final line was "## 支持的云平台". Yes. We need keep heading translated. Let's include that heading.

SDK Tencent Cloud использует полный пакет tencentcloud-sdk-nodejs и обращается по пространствам имён (cvm / lighthouse), что позволяет избежать ошибки "Cannot find module" при подключении неустановленных подпакетов продуктов. Полный пакет и все подпакеты продуктов размещаются в optionalDependencies; их отсутствие не влияет на остальные функции.

Философия работы: автоматизация в приоритете, для ручных операций есть playbook

Границы проектирования коннектора (определены владельцем):

1. Работа с публичными API 阿里云/腾讯云 — где есть чистый API (настройка ключей, обновление CDN, запросы экземпляров, разрешение DNS), приоритет отдаётся автоматизации с помощью инструментов.

2. Подключение к облачным серверам по SSH для выполнения команд — регистрация через server_add + удалённое выполнение через server_exec.

3. (Опционально) вызов браузерной автоматизации Kimi WebBridge — для операций в консоли, для которых нет публичного API (вход по QR-коду, чтение AK/SK, некоторые расширенные настройки CDN).

4. При ручных операциях пользователя необходимо предоставить описание «цель + процесс» — если API-возможности нет, коннектор выдаёт стандартные шаги, которые человек выполняет в консоли.

Конкретные playbook (включая команды, пути в консоли, известные подводные камни) централизованно поддерживаются в OPERATIONS.md.

Функции безопасности

• Аутентификация по SSH-ключу приоритетнее пароля

• Запросы к базе данных автоматически блокируют опасные операции (DROP/TRUNCATE/ALTER)

• Все чувствительные конфигурации (облачные AK, пути к SSH-приватным ключам) управляются через .env, .env исключён из .gitignore; сами файлы SSH-ключей храните в безопасном месте (например, ~/.ssh/), ссылайтесь на них по пути через поле privateKey, не включайте их в каталог проекта

• Защита от SQL-инъекций (параметризованные запросы, ограничение размера набора результатов)

• Механизм тайм-аута выполнения команд (по умолчанию 60 с, максимум 10 минут, настраивается)

• Проверка ввода целей обновления CDN (URL должен начинаться с http(s)://; путь обновления каталога должен заканчиваться на /)

• server_add при записи в .env выполняет проверку на совпадение имён, чтобы не перезаписать существующие серверы

• Для файла .env рекомендуется установить права только на чтение и запись для пользователя (chmod 600 .env)

• Регулярно меняйте облачные AK/ключи; создайте для коннектора выделенный облачный субаккаунт и следуйте принципу минимальных привилегий (подробнее см. выше «Мастер настройки → пользователи RAM»)

Руководство по расширению

Добавление новых инструментов

1. Создайте новый модуль в src/tools/

2. Экспортируйте функцию registerXxxTools(server: McpServer)

3. Зарегистрируйте в src/index.ts

Добавление новой облачной платформы / продукта

1. Создайте или расширьте обёртку SDK в src/clients/ (предпочтительно переиспользовать пространства имён полного пакета tencentcloud-sdk-nodejs)

2. Добавьте типы конфигурации в src/config.ts

3. Добавьте инструменты в src/tools/cloud.ts

Лицензия

MIT