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