shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

cloudstack-mcp-server

一个高性能的CloudStack MCP服务器，提供完整的虚拟机生命周期管理、基础设施发现和安全认证功能，支持通过MCP协议与AI助手和自动化工具集成。

article

README

🚀 CloudStack MCP Server

CloudStack MCP Server 是一个高性能的 MCP（模型上下文协议）服务器，用于集成 Apache CloudStack API。该服务器提供了一套完整的工具，可通过 MCP 协议管理 CloudStack 基础设施，实现与 AI 助手和自动化工具的无缝集成。

🚀 快速开始

安装

  1. 克隆仓库并安装依赖：

    git clone <repository-url>
cd cloudstack-mcp-server
npm install

  2. 配置环境变量： 在项目根目录下创建一个 .env 文件：

    CLOUDSTACK_API_URL=https://your-cloudstack-server/client/api
CLOUDSTACK_API_KEY=your-api-key
CLOUDSTACK_SECRET_KEY=your-secret-key
CLOUDSTACK_TIMEOUT=30000

  3. 构建项目：

    npm run build

  4. 启动服务器：

    # 开发模式（MCP 服务器）
npm run dev

# 生产模式（MCP 服务器）
npm start

# 命令行模式
npm run cli -- --help

MCP 客户端集成

将以下内容添加到你的 MCP 客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "cloudstack": {
      "command": "node",
      "args": ["/path/to/cloudstack-mcp-server/build/index.js"],
      "env": {
        "CLOUDSTACK_API_URL": "https://your-cloudstack-server/client/api",
        "CLOUDSTACK_API_KEY": "your-api-key",
        "CLOUDSTACK_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

命令行界面

若要直接通过命令行进行操作，可使用内置的命令行界面：

# 全局安装（可选）
npm link

# 使用命令行界面
cloudstack-cli list-vms --state Running
cloudstack-cli deploy-vm --service-offering-id 1 --template-id 2 --zone-id 3
cloudstack-cli get-vm --id 12345-67890-abcdef

# 查看所有可用命令
cloudstack-cli --help

详细的命令行文档请参阅 CLI.md。

✨ 主要特性

  • 🔧 完整的虚拟机生命周期管理：部署、启动、停止、重启和销毁虚拟机。
  • 🏗️ 基础设施发现：列出区域、模板和服务套餐。
  • 🔐 安全认证：使用 CloudStack API 凭证进行 HMAC - SHA1 签名请求。
  • ⚡ 高性能：采用高效的 TypeScript 实现，并具备完善的错误处理机制。
  • 🛡️ 类型安全：全面支持 TypeScript，拥有完整的接口。
  • 📊 丰富信息：提供详细的虚拟机元数据，包括 CPU、内存、网络和状态。
  • 🖥️ 命令行界面：可直接通过命令行进行交互式的 CloudStack 管理。
  • 🤖 MCP 集成：通过 MCP 协议与 AI 助手实现无缝集成。

📦 可用工具（共 45 个工具）

🖥️ 虚拟机管理（7 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_virtual_machines | 列出虚拟机，可选择过滤条件 | zoneid、state、keyword | | get_virtual_machine | 获取虚拟机详细信息 | id（必需） | | start_virtual_machine | 启动已停止的虚拟机 | id（必需） | | stop_virtual_machine | 停止正在运行的虚拟机 | id（必需）、forced（可选） | | reboot_virtual_machine | 重启虚拟机 | id（必需） | | destroy_virtual_machine | 按照正确的工作流程销毁虚拟机（处理所有状态） | id（必需）、confirm（必需）、expunge（可选） | | deploy_virtual_machine | 部署新的虚拟机（为高级区域自动选择网络） | serviceofferingid、templateid、zoneid（必需）、name、displayname、networkids（可选） |

⚙️ 虚拟机高级操作（4 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | scale_virtual_machine | 扩展（调整大小）虚拟机 | id、serviceofferingid、confirm（必需） | | migrate_virtual_machine | 将虚拟机迁移到其他主机 | virtualmachineid、confirm（必需）、hostid（可选） | | reset_password_virtual_machine | 重置虚拟机密码 | id、confirm（必需） | | change_service_offering_virtual_machine | 更改虚拟机的服务套餐 | id、serviceofferingid（必需） |

💾 存储管理（7 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_volumes | 列出存储卷 | virtualmachineid、type、zoneid | | create_volume | 创建新的存储卷 | name、zoneid（必需）、diskofferingid、size | | attach_volume | 将存储卷附加到虚拟机 | id、virtualmachineid（必需） | | detach_volume | 从虚拟机分离存储卷 | id、confirm（必需） | | resize_volume | 调整存储卷大小 | id、size、confirm（必需） | | create_snapshot | 创建存储卷的快照 | volumeid（必需）、name | | list_snapshots | 列出存储卷快照 | volumeid、snapshottype |

🌐 网络管理（7 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_networks | 列出网络 | zoneid、type | | create_network | 创建新的网络 | name、networkofferingid、zoneid（必需）、displaytext | | list_public_ip_addresses | 列出公共 IP 地址 | zoneid、associatednetworkid | | associate_ip_address | 获取新的公共 IP 地址 | zoneid（必需）、networkid | | enable_static_nat | 为 IP 地址启用静态 NAT | ipaddressid、virtualmachineid（必需） | | create_firewall_rule | 创建防火墙规则 | ipaddressid、protocol（必需）、startport、endport、cidrlist | | list_load_balancer_rules | 列出负载均衡规则 | publicipid、zoneid |

📊 监控与分析（5 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_virtual_machine_metrics | 获取虚拟机性能指标 | ids | | list_events | 列出 CloudStack 事件 | type、level、startdate、pagesize | | list_alerts | 列出系统警报 | type | | list_capacity | 列出系统容量信息 | zoneid、type | | list_async_jobs | 列出异步作业 | jobstatus、jobresulttype |

👥 账户与用户管理（4 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_accounts | 列出 CloudStack 账户 | domainid、accounttype | | list_users | 列出用户 | accountid、username | | list_domains | 列出 CloudStack 域 | name | | list_usage_records | 列出资源使用记录 | startdate、enddate（必需）、type |

🏗️ 基础设施发现（2 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_zones | 列出所有可用区域 | available（可选） | | list_templates | 列出可用的虚拟机模板 | templatefilter、zoneid（可选） |

🔧 系统管理（5 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_hosts | 列出物理主机 | zoneid、type、state | | list_clusters | 列出主机集群 | zoneid | | list_storage_pools | 列出存储池 | zoneid、clusterid | | list_system_vms | 列出系统虚拟机 | zoneid、systemvmtype | | list_service_offerings | 列出服务套餐 | name、domainid |

🔐 安全与合规（4 个工具）

| 工具 | 描述 | 参数 | |------|-------------|------------| | list_ssh_key_pairs | 列出 SSH 密钥对 | name | | create_ssh_key_pair | 创建新的 SSH 密钥对 | name（必需） | | list_security_groups | 列出安全组 | securitygroupname | | create_security_group_rule | 创建安全组入站规则 | securitygroupid、protocol（必需）、startport、endport、cidrlist |

💻 使用示例

列出虚拟机

{
  "tool": "list_virtual_machines",
  "arguments": {
    "state": "Running",
    "zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8"
  }
}

部署新的虚拟机

{
  "tool": "deploy_virtual_machine",
  "arguments": {
    "serviceofferingid": "c6f99499-7f59-4138-9427-a09db13af2bc",
    "templateid": "7d4a7bb5-2409-4c8f-8537-6bbdc8a4e5c1",
    "zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8",
    "name": "my-new-vm",
    "displayname": "My New VM"
  }
}

📚 详细文档

项目结构

├── src/
│   ├── index.ts              # MCP 服务器入口点
│   ├── server.ts             # 主要的 MCP 服务器实现
│   ├── cli.ts                # 命令行界面
│   └── cloudstack-client.ts  # CloudStack API 客户端
├── build/                    # 编译后的 JavaScript 输出
├── CLI.md                   # 命令行文档
├── package.json             # 依赖项和脚本
├── tsconfig.json            # TypeScript 配置
└── .env                     # 环境变量（不在仓库中）

架构概述

  • src/index.ts：MCP 服务器入口点，负责加载环境变量并启动服务器。
  • src/server.ts：全面的 MCP 服务器实现，包含 45 个以上的工具处理程序、错误管理和 CloudStack 集成。
  • src/cli.ts：命令行界面，通过 JSON - RPC 与 MCP 服务器通信，实现直接的 CloudStack 管理。
  • src/cloudstack-client.ts：强大的 CloudStack API 客户端，具备 HMAC - SHA1 认证、类型安全的接口和完善的错误处理。

配置

必需的环境变量

| 变量 | 描述 | 示例 | |----------|-------------|---------| | CLOUDSTACK_API_URL | CloudStack API 端点 | http://cloudstack.example.com:8080/client/api | | CLOUDSTACK_API_KEY | CloudStack API 密钥 | your-32-character-api-key | | CLOUDSTACK_SECRET_KEY | CloudStack 密钥 | your-secret-key |

可选的环境变量

| 变量 | 描述 | 默认值 | |----------|-------------|---------| | CLOUDSTACK_TIMEOUT | 请求超时时间（毫秒） | 30000 |

开发

构建命令

# 将 TypeScript 编译为 JavaScript
npm run build

# 以热重载模式运行 MCP 服务器
npm run dev

# 在开发模式下运行命令行界面
npm run dev:cli -- list-vms --help

# 运行编译后的 MCP 服务器
npm start

# 运行编译后的命令行界面
npm run cli -- list-vms --help

# 仅进行类型检查
npx tsc --noEmit

代码质量

  • TypeScript：启用严格模式，确保全面的类型安全。
  • 错误处理：具备完善的错误处理机制，使用 MCP 错误类型。
  • 异步/等待：全程采用现代异步模式。
  • 模块化设计：清晰的关注点分离。

安全

  • HMAC - SHA1 签名：所有 API 请求都进行加密签名。
  • 无凭证存储：仅从环境变量中读取凭证。
  • 请求验证：对所有工具参数进行输入验证。
  • 错误清理：从错误消息中过滤敏感信息。

兼容性

  • CloudStack：与 CloudStack 4.11 及以上版本兼容。
  • Node.js：需要 Node.js 18 及以上版本。
  • MCP 协议：实现了 MCP SDK 0.5.0 及以上版本。
  • TypeScript：基于 TypeScript 5.0 及以上版本构建。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端