Cloudstack MCP Server

🚀 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 个工具）

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

💾 存储管理（7 个工具）

🌐 网络管理（7 个工具）

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

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

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

🔧 系统管理（5 个工具）

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

💻 使用示例

列出虚拟机

{
  "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 认证、类型安全的接口和完善的错误处理。

配置

必需的环境变量

可选的环境变量

开发

构建命令

# 将 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 文件。