🚀 CloudStack MCP Server
CloudStack MCP Server 是一个高性能的 MCP（模型上下文协议）服务器，用于集成 Apache CloudStack API。该服务器提供了一套完整的工具，可通过 MCP 协议管理 CloudStack 基础设施，实现与 AI 助手和自动化工具的无缝集成。
🚀 快速开始
安装
-
克隆仓库并安装依赖：
git clone
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
-
启动服务器：
npm run dev
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 |
开发
构建命令
npm run build
npm run dev
npm run dev:cli -- list-vms --help
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 文件。
