CloudStack MCP服务器
用于Apache CloudStack API集成的高性能MCP(模型上下文协议)服务器。该服务器提供了通过MCP协议管理CloudStack基础设施的全面工具,实现了与AI助手和自动化工具的无缝集成。
特性
- 🔧 完整的VM生命周期管理:部署、启动、停止、重新启动和销毁虚拟机
- 🏗️ 基础设施发现:列出区域、模板和服务选项
- 🔐 安全认证:使用CloudStack API凭据的HMAC-SHA1签名请求
- ⚡ 高性能:高效的TypeScript实现,具有适当的错误处理
- 🛡️ 类型安全:完全支持TypeScript,具有全面的接口
- 📊 丰富的信息:详细的VM元数据,包括CPU、内存、网络和状态
- 🖥️ 命令行接口:用于交互式CloudStack管理的直接CLI访问
- 🤖 MCP集成:通过MCP协议与AI助手无缝集成
快速开始
安装
- 克隆和安装依赖关系:```bash
git clone
cd cloudstack-mcp-server
npm install
1. **配置环境变量:**
创建一个 `.env` 项目根目录中的文件:```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
- 构建项目:```bash
npm run build
1. **运行服务器:**```bash
# Development mode (MCP server)
npm run dev
# Production mode (MCP server)
npm start
# CLI mode
npm run cli -- --help
MCP客户端集成
添加到您的MCP客户端配置中(例如,Claude Desktop):```json
{
"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:```bash
# 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 |
示例用法
列出虚拟机```json
{
"tool": "list_virtual_machines",
"arguments": {
"state": "Running",
"zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8"
}
}
### 部署新虚拟机```json
{
"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` |
## 发展
### 构建命令```bash
# 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-有关详细信息,请参阅许可证文件