云栈-MCP服务器

Name: 云栈-MCP服务器
Author: phantosmax

作者：phantosmax6 星标更新：2025-06-18

安装使用来源：spider==github.com

项目介绍

CloudStack MCP 服务器

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

特性

🔧 完整虚拟机生命周期管理：部署、启动、停止、重启和销毁虚拟机
🏗️ 基础设施发现：列出区域、模板和服务提供选项
🔐 安全认证：使用 CloudStack API 凭证进行 HMAC-SHA1 签名请求
⚡ 高性能：高效的 TypeScript 实现，具有适当的错误处理
🛡️ 类型安全：完整的 TypeScript 支持，具有全面的接口
📊 丰富的信息：详细的虚拟机元数据，包括 CPU、内存、网络和状态
🖥️ 命令行界面：直接 CLI 访问以进行交互式 CloudStack 管理
🤖 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
```

运行服务器：

# 开发模式（MCP 服务器）
npm run dev

# 生产模式（MCP 服务器）
npm start

# CLI 模式
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：

# 全局安装（可选）
npm link

# 使用 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

# 查看所有可用命令
cloudstack-cli --help

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

可用工具（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                   # CLI 文档
├── package.json             # 依赖项和脚本
├── tsconfig.json            # TypeScript 配置
└── .env                     # 环境变量（不在仓库中）

架构概述

src/index.ts：加载环境变量并启动 MCP 服务器的入口点
src/server.ts：包含 45 多个工具处理器、错误管理和 CloudStack 集成的全面 MCP 服务器实现
src/cli.ts：通过 JSON-RPC 通信与 MCP 服务器直接管理 CloudStack 的命令行界面
src/cloudstack-client.ts：具有 HMAC-SHA1 认证、类型安全接口和全面错误处理的健壮 CloudStack API 客户端

配置

必需的环境变量

变量	描述	示例
`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`

开发

构建命令

# 将 TypeScript 编译为 JavaScript
npm run build

# 以开发模式运行 MCP 服务器，带有热重载
npm run dev

# 以开发模式运行 CLI
npm run dev:cli -- list-vms --help

# 运行编译后的 MCP 服务器
npm start

# 运行编译后的 CLI
npm run cli -- list-vms --help

# 仅进行类型检查
npx tsc --noEmit

代码质量

TypeScript：启用严格模式的完全类型安全
错误处理：具有 MCP 错误类型的全面错误处理
Async/Await：整个项目采用现代异步模式
模块化设计：清晰的责任分离

安全

HMAC-SHA1 签名：所有 API 请求都进行了加密签名
无凭据存储：仅从环境变量读取凭据
请求验证：所有工具参数上的输入验证
错误净化：从错误消息中过滤敏感信息

兼容性

CloudStack：兼容 CloudStack 4.11+
Node.js：需要 Node.js 18+
MCP 协议：实现 MCP SDK 0.5.0+
TypeScript：使用 TypeScript 5.0+ 构建

许可证

MIT - 详情见 LICENSE 文件