CloudOps MCP Server

CloudOps MCP Server

统一云运维 MCP (Model Context Protocol) 服务器，让 AI Agent 具备全栈云运维能力。

一个 MCP Server 同时管理阿里云 + 腾讯云，覆盖服务器管理、项目部署、数据库查询、文件操作、云实例查询、DNS/CDN 管理 6 大场景，26 个工具。

版本

• 当前版本：v1.0.0（详见 CHANGELOG.md）。

文档导航

• README.md（本文件）：连接器总文档 —— 工具清单、一键安装（复制粘贴给 AI）、手动安装、配置向导、架构、工具详解、扩展指南。
• OPERATIONS.md：真实运维 Playbook（P1–P8），沉淀「获取密钥 / 上传 SSH 公钥 / 建立 NOPASSWD sudo / CDN 改源站」等「目标 + 流程」式实操手册。需要手动操作云控制台时优先查它。
• CHANGELOG.md：版本更新记录。

工具总览（26 个）

一键安装（复制粘贴给 AI）⭐ 推荐

仓库已公开，任何支持第三方 MCP 的 AI 工具都能直接克隆使用。把下面这段话原样复制给你的 AI 助手，它会自己完成：克隆 → 读文档 → 安装依赖 → 配置 → 注册连接器 → 验证 26 个工具。适配 WorkBuddy、Hermes Agent、Claude Code、Codex CLI 等主流 Agent。比手动安装更快，优先使用。

请帮我安装并学会使用 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 已排除）。

各客户端注册方式

把下面的 <路径> 换成你的实际克隆路径（如 E:/WorkSpace/cloud-ops-mcp、/home/user/cloud-ops-mcp）。.env 按源码路径自动加载（不依赖进程启动目录），因此以下注册方式均无需额外设置工作目录。

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（一条命令，需先 cd 到项目目录或在项目内执行）：

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

注册后重启对应 AI 客户端（或执行其 MCP 重载命令，如 Hermes 的 /reload-mcp），即可看到 server_exec、deploy_project、db_query、cdn_refresh 等 26 个工具。

手动安装（快速开始）

以下为手动安装步骤（克隆 → 配置 → 注册 → 验证）。想更快？用上面的「一键安装（复制粘贴给 AI）」让 AI 自动完成。

1. 克隆 & 安装

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

项目使用 tsx 作为 TypeScript 运行时，无需编译步骤。

2. 配置

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

最小配置（只需 SSH）：

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

完整配置项参见 .env.example，支持多服务器、数据库、阿里云/腾讯云 AK。

💡 运行时注册服务器：除了手改 .env 的 SSH_SERVERS，也可以用 server_add 工具在运行时注册（写入 .env 并热更新内存缓存，无需重启连接器）。详见下文「工具详解 → server_add」。

3. 注册到 MCP 客户端（任意支持第三方 MCP 的 AI 工具）

本连接器不是 WorkBuddy 专属。只要你的 AI 工具满足两点即可使用：

1. 能安装 kimi-webbridge 这个 skill（用于无公开 API 的控制台自动化兜底）；
2. 支持安装第三方 MCP 连接器（stdio 协议）。常见如 WorkBuddy、Claude Desktop、Cursor、VS Code（Cline/Continue 等扩展）均可。

通用注册片段（把 /absolute/path/to/cloud-ops-mcp 换成你的实际路径）：

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

各客户端配置文件位置：

cwd 必须指向项目根目录，MCP Server 需要从该目录加载 .env 和 node_modules。配置向导默认不会自动改写任何客户端的 MCP 配置；如需向导自动写入，可设置环境变量 CLOUD_OPS_MCP_CONFIG_PATH 指向目标配置文件路径（可选）。

4. 验证

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

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

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

配置向导（推荐）

配置向导是一个 Web UI，让你用浏览器可视化编辑 .env 的全部内容——既能自动获取（依赖 Kimi WebBridge 扫云控制台）云实例与密钥并回填，也能手动填写 SSH 私钥路径、远程登录密码、数据库账号密码、部署默认等所有字段。0 基础用户也能直接上手。

你仍可以随时直接手改 .env 文件（参见 OPERATIONS.md 手动 playbook）；向导只是更友好的入口，不是唯一方式。

需要先准备哪些配置（必要 / 可选）

只有 SSH 服务器是必须的；云 AK、数据库、部署默认都是「用到才配」。纯手动部署（如只 server_exec + deploy_project）可只配 SSH。

前置条件

• Kimi WebBridge 浏览器自动化守护进程（npm run config 会自动检测 / 启动 / 安装；也可手动装）
• 浏览器扩展需手动安装：https://www.kimi.com/zh-cn/features/webbridge

Kimi WebBridge 的定位：它用于那些没有干净公开 API 的控制台操作（例如扫码登录云厂商控制台、读取 AK/SK、部分 CDN 高级配置）。对于已有公开 API 的能力（密钥配置、CDN 缓存刷新、实例查询等），优先使用工具自动化，Kimi WebBridge 是「无 API 时的可选兜底」。

使用步骤

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

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

Kimi WebBridge 自动处理：npm run config 会自动检测守护进程——已在运行则直接用；已安装未运行则自动启动；未安装则按官方命令自动安装（Windows: irm https://cdn.kimi.com/webbridge/install.ps1 | iex；macOS/Linux: curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash）再启动。自动安装失败或你想手动时，按上面命令自行安装即可。

⚠️ 浏览器扩展需手动安装：守护进程可自动化安装，但浏览器扩展（让守护进程接管你真实浏览器会话）无法自动安装，请到 https://www.kimi.com/zh-cn/features/webbridge 手动安装并登录。WebBridge 仅用于「云 AK 自动获取」兜底；未安装时向导仍可手动填写 .env，不阻断。

RAM 用户（推荐，自动）

阿里云与腾讯云在「创建密钥」时都会弹出建议使用 RAM/子账号而非主账号密钥的确认框。配置向导现在会识别该弹窗并自动转入子用户流程：

1. 在 RAM/CAM 控制台创建专用子用户 cloud-ops-mcp（勾选编程访问）；
2. 为该子用户生成 AccessKey，读取 KeyId/Secret；
3. 尽力附加连接器所需的最小权限策略（ECS/SWAS/Lighthouse 只读、CDN 刷新、DNS 解析）；
4. 把子用户密钥写入 .env，绝不落主账号密钥。

若自动附加策略失败，向导会生成 MANUAL_STEPS.md，内含需手动附加的最小权限策略 JSON，按步骤补齐即可。所有控制台 UI 检测信号均为可配置列表，识别失败时一律降级为手动步骤，不会把「点过弹窗」误判为成功。

最小权限（禁用全管理员 AdministratorAccess / QcloudAdministrator）：阿里云 AliyunECSReadOnlyAccess / AliyunSWASReadOnlyAccess / AliyunCDNFullAccess / AliyunDNSFullAccess；腾讯云 QcloudCVMReadOnlyAccess / QcloudLighthouseReadOnlyAccess / QcloudCDNFullAccess / QcloudDNSPodFullAccess。

重跑向导的幂等行为（重要）

配置向导可安全反复运行，已针对「重复造 AK / 重复建子用户」做了幂等处理：

1. 已有 AK 不会重复获取：.env 里已存在阿里云 ALIBABA_CLOUD_ACCESS_KEY_ID 时，点「阿里云全自动配置」会默认保留现有配置、跳过浏览器自动获取，并在日志提示「已保留现有」。若确实要重新抓取，点击「重新获取」按钮即可（走强制刷新路径）。
2. RAM/CAM 子用户自动复用：向导固定使用名为 cloud-ops-mcp 的子用户。重跑时先查该子用户是否已存在——存在则复用，不会重复创建（阿里云 CreateUser 同名会直接报错，这正是早期重复运行的坑）。
3. AccessKey 轮换而非堆积：复用既有子用户时，向导会先清理该子用户下已有的 AccessKey（best-effort），再新建一对写入 .env，避免密钥超过 2 把上限或长期堆积。
4. 留痕方便清理：凡经向导创建/复用 RAM 子用户，都会在 .env 写入 ALIYUN_RAM_USER=cloud-ops-mcp 标记。日后想彻底移除时，到阿里云 RAM 控制台删除该子用户即可（删除前请确认连接器不再使用其密钥）。

一句话：反复点「全自动配置」是安全的——它要么保留、要么复用、要么轮换，不会凭空多出子用户或密钥。

配置完成后关闭守护进程

# 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

配置向导是可选的。手动编辑 .env 文件永远可用（参见 OPERATIONS.md 中的手动 playbook）。

配置向导 API 接口

向导后端（Express）暴露以下接口，供前端调用：

全自动流程（简述）

• 阿里云：打开 ECS 控制台 → 检测/扫码登录 → 从实例列表提取 IP 与名称 → 跳 RAM「API 密钥」→ 识别「建议用 RAM 用户」弹窗并转子用户流程 → 取 AK/SK → 回填表单。
• 腾讯云：打开 CVM 控制台 → 检测/扫码登录 → 提取实例 → 跳 CAM「API 密钥」→ 识别弹窗转子用户流程 → 取 SecretId/Key → 回填表单。

两朵云可分别点击，配置会合并进同一个 .env。

注意事项

1. 浏览器自动化可能需要微调：云控制台页面结构会变，自动提取失败时会展示页面预览便于排查。
2. SecretKey 可能无法自动提取：部分云平台安全策略会隐藏 Secret，此时需手动复制粘贴。
3. SSH 密钥路径：自动配置默认 ~/.ssh/id_rsa，若路径不同请在配置预览中手动修改（Windows 下建议用 /C:/Users/<LOCAL_USER>/.ssh/... 绝对路径）。
4. 多云平台合并：可分别点击阿里云 / 腾讯云按钮，两边配置会合并进同一个 .env。

架构

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 的控制台操作

项目结构

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                    # 项目总文档（本文件）

工具详解

server_exec — 远程命令执行

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

server_add — 运行时注册 SSH 服务器

参数: 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 — 项目部署

参数: 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(SQL), maxRows(默认100)
安全: 自动阻止 DROP/TRUNCATE/ALTER 等危险操作

file_read / file_write / file_search — 文件操作

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

cloud_list_instances — 云实例列表

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

cdn_refresh — CDN 缓存刷新（自动化，无需进控制台）

参数: 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 刷新任务进度查询（v1.0.0 新增）

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

更多「目标 + 流程」式手动操作说明（获取密钥、上传 SSH 公钥、建立 NOPASSWD sudo、CDN 改主源站等），参见 OPERATIONS.md。

常见使用场景

以下是 AI Agent 通过自然语言驱动连接器的典型流程：

• 查看服务器状态：「看看 Tencent-LH 的 CPU 和内存」 → server_info → 表格展示。
• 部署项目：「把 myapp 部署到 Tencent-LH」 → deploy_project（SSH 拉取最新代码 → 构建 → 重启）。
• 查询数据库：「查 prod-db 用户表前 10 条」 → db_query（经 SSH 隧道连库，自动拦截危险 SQL）。
• 管理云资源：「列出腾讯云广州区所有 Lighthouse 实例」 → cloud_list_instances tencent。
• 刷新 CDN：「刷新 <YOUR_DOMAIN> 缓存」 → cdn_refresh。

支持的云平台

腾讯云 SDK 采用整包 tencentcloud-sdk-nodejs 并按命名空间访问（cvm / lighthouse），避免引入未安装的产品分包导致 "Cannot find module" 错误。整包与各产品分包均放在 optionalDependencies 中，未安装不影响其他功能。

操作理念：自动化优先，手动有 playbook

连接器的设计边界（来自 owner 定义）：

1. 操作阿里云/腾讯云公开 API —— 凡有干净 API 的（密钥配置、CDN 刷新、实例查询、DNS 解析），优先用工具自动化。
2. 通过 SSH 连接云服务器执行命令 —— server_add 注册 + server_exec 远程执行。
3. （可选）调用 Kimi WebBridge 浏览器自动化 —— 用于没有公开 API 的控制台操作（扫码登录、读取 AK/SK、部分 CDN 高级配置）。
4. 用户手动操作时必须给「目标 + 流程」说明 —— 缺 API 能力的，由连接器产出标准步骤，由人去控制台执行。

具体 playbook（含命令、控制台路径、已知坑）统一维护在 OPERATIONS.md。

安全特性

• SSH 密钥认证优先于密码
• 数据库查询自动阻止危险操作 (DROP/TRUNCATE/ALTER)
• 所有敏感配置（云 AK、SSH 私钥路径）通过 .env 管理，.env 已在 .gitignore 中排除；SSH 私钥实体请放在你自己的安全位置（如 ~/.ssh/），经 privateKey 字段按路径引用，勿纳入项目目录
• SQL 注入防护（参数化查询，限制结果集大小）
• 命令执行超时机制（默认 60s，最大 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. 在 src/clients/ 下创建或扩展 SDK 封装（优先复用整包 tencentcloud-sdk-nodejs 的命名空间）
2. 在 src/config.ts 添加配置类型
3. 在 src/tools/cloud.ts 添加工具

许可证

MIT