使用说明

CloudStack MCP服务器

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

特性

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

快速开始

安装

克隆和安装依赖关系：

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

配置环境变量： 创建一个 .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

构建项目：
```
npm run build
```

运行服务器：

# Development mode (MCP server)
npm run dev

# Production mode (MCP server)
npm start

# CLI mode
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"
      }
    }
  }
}

命令行接口

对于直接命令行访问，请使用内置CLI：

# Install globally (optional)
npm link

# Use the CLI
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

# See all available commands
cloudstack-cli --help

有关详细的CLI文档，请参阅 CLI.md.

可用工具（45个工具）

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

工具	说明	参数
`list_virtual_machines`	列出具有可选筛选功能的虚拟机	`zoneid`, `state`, `keyword`
`get_virtual_machine`	获取详细的VM信息	`id` （必填）
`start_virtual_machine`	启动已停止的虚拟机	`id` （必填）
`stop_virtual_machine`	停止正在运行的虚拟机	`id` （必填）， `forced` （可选）
`reboot_virtual_machine`	重新启动虚拟机	`id` （必填）
`destroy_virtual_machine`	使用适当的工作流销毁VM（处理所有状态）	`id` （必填）， `confirm` （必填）， `expunge` （可选）
`deploy_virtual_machine`	部署新的虚拟机（自动为高级区域选择网络）	`serviceofferingid`, `templateid`, `zoneid` （必填）， `name`, `displayname`, `networkids` （可选）

⚙️ VM高级操作（4个工具）

工具	说明	参数
`scale_virtual_machine`	缩放（调整大小）虚拟机	`id`, `serviceofferingid`, `confirm` （必填）
`migrate_virtual_machine`	将VM迁移到另一台主机	`virtualmachineid`, `confirm` （必填）， `hostid` （可选）
`reset_password_virtual_machine`	重置虚拟机的密码	`id`, `confirm` （必填）
`change_service_offering_virtual_machine`	更改VM的服务选项	`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`	列出可用的VM模板	`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 entry point
│   ├── server.ts             # Main MCP server implementation
│   ├── cli.ts                # Command-line interface
│   └── cloudstack-client.ts  # CloudStack API client
├── build/                    # Compiled JavaScript output
├── CLI.md                   # CLI documentation
├── package.json             # Dependencies and scripts
├── tsconfig.json            # TypeScript configuration
└── .env                     # Environment variables (not in repo)

架构概述

src/index.ts：加载环境变量并启动服务器的MCP服务器入口点
src/server.ts：全面的MCP服务器实施，包括45个以上的工具处理程序、错误管理和CloudStack集成
src/cli.ts：通过与MCP服务器的JSON-RPC通信进行直接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`

发展

构建命令

# Build TypeScript to JavaScript
npm run build

# Run MCP server in development mode with hot reload
npm run dev

# Run CLI in development mode
npm run dev:cli -- list-vms --help

# Run compiled MCP server
npm start

# Run compiled CLI
npm run cli -- list-vms --help

# Type checking only
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-有关详细信息，请参阅许可证文件