Cloudstack

A high-performance MCP (Model Context Protocol) server for Apache CloudStack API integration. This server provides comprehensive tools for managing CloudStack infrastructure through the MCP protocol, enabling seamless integration with AI assistants and automation tools.

Features

• 🔧 Complete VM Lifecycle Management: Deploy, start, stop, reboot, and destroy virtual machines
• 🏗️ Infrastructure Discovery: List zones, templates, and service offerings
• 🔐 Secure Authentication: HMAC-SHA1 signed requests with CloudStack API credentials
• ⚡ High Performance: Efficient TypeScript implementation with proper error handling
• 🛡️ Type Safety: Full TypeScript support with comprehensive interfaces
• 📊 Rich Information: Detailed VM metadata including CPU, memory, network, and status
• 🖥️ Command Line Interface: Direct CLI access for interactive CloudStack management
• 🤖 MCP Integration: Seamless integration with AI assistants via MCP protocol

Quick Start

Installation

1. Clone and install dependencies:

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

2. Configure environment variables: Create a .env file in the project root:

   CLOUDSTACK_API_URL=https://your-cloudstack-server/client/api
   CLOUDSTACK_API_KEY=your-api-key
   CLOUDSTACK_SECRET_KEY=your-secret-key
   CLOUDSTACK_TIMEOUT=30000
   

3. Build the project:

   npm run build
   

4. Run the server:

   # Development mode (MCP server)
   npm run dev
   
   # Production mode (MCP server)
   npm start
   
   # CLI mode
   npm run cli -- --help
   

MCP Client Integration

Add to your MCP client configuration (e.g., 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"
      }
    }
  }
}

Command Line Interface

For direct command-line access, use the built-in 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

For detailed CLI documentation, see CLI.md.

Available Tools (45 Tools)

🖥️ Virtual Machine Management (7 Tools)

Tool	Description	Parameters
list_virtual_machines	List VMs with optional filtering	zoneid, state, keyword
get_virtual_machine	Get detailed VM information	id (required)
start_virtual_machine	Start a stopped virtual machine	id (required)
stop_virtual_machine	Stop a running virtual machine	id (required), forced (optional)
reboot_virtual_machine	Reboot a virtual machine	id (required)
destroy_virtual_machine	Destroy a VM with proper workflow (handles all states)	id (required), confirm (required), expunge (optional)
deploy_virtual_machine	Deploy a new VM (auto-selects network for Advanced zones)	serviceofferingid, templateid, zoneid (required), name, displayname, networkids (optional)

⚙️ VM Advanced Operations (4 Tools)

Tool	Description	Parameters
scale_virtual_machine	Scale (resize) a virtual machine	id, serviceofferingid, confirm (required)
migrate_virtual_machine	Migrate VM to another host	virtualmachineid, confirm (required), hostid (optional)
reset_password_virtual_machine	Reset password for a virtual machine	id, confirm (required)
change_service_offering_virtual_machine	Change service offering for a VM	id, serviceofferingid (required)

💾 Storage Management (7 Tools)

Tool	Description	Parameters
list_volumes	List storage volumes	virtualmachineid, type, zoneid
create_volume	Create a new storage volume	name, zoneid (required), diskofferingid, size
attach_volume	Attach a volume to a virtual machine	id, virtualmachineid (required)
detach_volume	Detach a volume from a virtual machine	id, confirm (required)
resize_volume	Resize a storage volume	id, size, confirm (required)
create_snapshot	Create a snapshot of a volume	volumeid (required), name
list_snapshots	List volume snapshots	volumeid, snapshottype

🌐 Networking (7 Tools)

Tool	Description	Parameters
list_networks	List networks	zoneid, type
create_network	Create a new network	name, networkofferingid, zoneid (required), displaytext
list_public_ip_addresses	List public IP addresses	zoneid, associatednetworkid
associate_ip_address	Acquire a new public IP address	zoneid (required), networkid
enable_static_nat	Enable static NAT for an IP address	ipaddressid, virtualmachineid (required)
create_firewall_rule	Create a firewall rule	ipaddressid, protocol (required), startport, endport, cidrlist
list_load_balancer_rules	List load balancer rules	publicipid, zoneid

📊 Monitoring & Analytics (5 Tools)

Tool	Description	Parameters
list_virtual_machine_metrics	Get virtual machine performance metrics	ids
list_events	List CloudStack events	type, level, startdate, pagesize
list_alerts	List system alerts	type
list_capacity	List system capacity information	zoneid, type
list_async_jobs	List asynchronous jobs	jobstatus, jobresulttype

👥 Account & User Management (4 Tools)

Tool	Description	Parameters
list_accounts	List CloudStack accounts	domainid, accounttype
list_users	List users	accountid, username
list_domains	List CloudStack domains	name
list_usage_records	List resource usage records	startdate, enddate (required), type

🏗️ Infrastructure Discovery (2 Tools)

Tool	Description	Parameters
list_zones	List all available zones	available (optional)
list_templates	List available VM templates	templatefilter, zoneid (optional)

🔧 System Administration (5 Tools)

Tool	Description	Parameters
list_hosts	List physical hosts	zoneid, type, state
list_clusters	List host clusters	zoneid
list_storage_pools	List storage pools	zoneid, clusterid
list_system_vms	List system virtual machines	zoneid, systemvmtype
list_service_offerings	List service offerings	name, domainid

🔐 Security & Compliance (4 Tools)

Tool	Description	Parameters
list_ssh_key_pairs	List SSH key pairs	name
create_ssh_key_pair	Create a new SSH key pair	name (required)
list_security_groups	List security groups	securitygroupname
create_security_group_rule	Create a security group ingress rule	securitygroupid, protocol (required), startport, endport, cidrlist

Example Usage

List Virtual Machines

{
  "tool": "list_virtual_machines",
  "arguments": {
    "state": "Running",
    "zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8"
  }
}

Deploy New Virtual Machine

{
  "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"
  }
}

Project Structure

├── 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)

Architecture Overview

• src/index.ts: MCP server entry point that loads environment variables and starts the server
• src/server.ts: Comprehensive MCP server implementation with 45+ tool handlers, error management, and CloudStack integration
• src/cli.ts: Command-line interface for direct CloudStack management via JSON-RPC communication with the MCP server
• src/cloudstack-client.ts: Robust CloudStack API client with HMAC-SHA1 authentication, type-safe interfaces, and comprehensive error handling

Configuration

Required Environment Variables

Variable	Description	Example
CLOUDSTACK_API_URL	CloudStack API endpoint	http://cloudstack.example.com:8080/client/api
CLOUDSTACK_API_KEY	CloudStack API key	your-32-character-api-key
CLOUDSTACK_SECRET_KEY	CloudStack secret key	your-secret-key

Optional Environment Variables

Variable	Description	Default
CLOUDSTACK_TIMEOUT	Request timeout (milliseconds)	30000

Development

Build Commands

# 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

Code Quality

• TypeScript: Full type safety with strict mode enabled
• Error Handling: Comprehensive error handling with MCP error types
• Async/Await: Modern async patterns throughout
• Modular Design: Clean separation of concerns

Security

• HMAC-SHA1 Signing: All API requests are cryptographically signed
• No Credential Storage: Credentials read from environment variables only
• Request Validation: Input validation on all tool parameters
• Error Sanitization: Sensitive information filtered from error messages

Compatibility

• CloudStack: Compatible with CloudStack 4.11+
• Node.js: Requires Node.js 18+
• MCP Protocol: Implements MCP SDK 0.5.0+
• TypeScript: Built with TypeScript 5.0+

License

MIT - See LICENSE file for details