cloudstack-mcp-server

phantosmax/cloudstack-mcp-server

3.4

If you are the rightful owner of cloudstack-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

CloudStack MCP Server is a high-performance server designed for seamless integration with Apache CloudStack API, enabling efficient management of CloudStack infrastructure through the Model Context Protocol (MCP).

CloudStack MCP Server

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 .

Available Tools (45 Tools)

šŸ–„ļø Virtual Machine Management (7 Tools)

ToolDescriptionParameters
list_virtual_machinesList VMs with optional filteringzoneid, state, keyword
get_virtual_machineGet detailed VM informationid (required)
start_virtual_machineStart a stopped virtual machineid (required)
stop_virtual_machineStop a running virtual machineid (required), forced (optional)
reboot_virtual_machineReboot a virtual machineid (required)
destroy_virtual_machineDestroy a VM with proper workflow (handles all states)id (required), confirm (required), expunge (optional)
deploy_virtual_machineDeploy a new VM (auto-selects network for Advanced zones)serviceofferingid, templateid, zoneid (required), name, displayname, networkids (optional)

āš™ļø VM Advanced Operations (4 Tools)

ToolDescriptionParameters
scale_virtual_machineScale (resize) a virtual machineid, serviceofferingid, confirm (required)
migrate_virtual_machineMigrate VM to another hostvirtualmachineid, confirm (required), hostid (optional)
reset_password_virtual_machineReset password for a virtual machineid, confirm (required)
change_service_offering_virtual_machineChange service offering for a VMid, serviceofferingid (required)

šŸ’¾ Storage Management (7 Tools)

ToolDescriptionParameters
list_volumesList storage volumesvirtualmachineid, type, zoneid
create_volumeCreate a new storage volumename, zoneid (required), diskofferingid, size
attach_volumeAttach a volume to a virtual machineid, virtualmachineid (required)
detach_volumeDetach a volume from a virtual machineid, confirm (required)
resize_volumeResize a storage volumeid, size, confirm (required)
create_snapshotCreate a snapshot of a volumevolumeid (required), name
list_snapshotsList volume snapshotsvolumeid, snapshottype

🌐 Networking (7 Tools)

ToolDescriptionParameters
list_networksList networkszoneid, type
create_networkCreate a new networkname, networkofferingid, zoneid (required), displaytext
list_public_ip_addressesList public IP addresseszoneid, associatednetworkid
associate_ip_addressAcquire a new public IP addresszoneid (required), networkid
enable_static_natEnable static NAT for an IP addressipaddressid, virtualmachineid (required)
create_firewall_ruleCreate a firewall ruleipaddressid, protocol (required), startport, endport, cidrlist
list_load_balancer_rulesList load balancer rulespublicipid, zoneid

šŸ“Š Monitoring & Analytics (5 Tools)

ToolDescriptionParameters
list_virtual_machine_metricsGet virtual machine performance metricsids
list_eventsList CloudStack eventstype, level, startdate, pagesize
list_alertsList system alertstype
list_capacityList system capacity informationzoneid, type
list_async_jobsList asynchronous jobsjobstatus, jobresulttype

šŸ‘„ Account & User Management (4 Tools)

ToolDescriptionParameters
list_accountsList CloudStack accountsdomainid, accounttype
list_usersList usersaccountid, username
list_domainsList CloudStack domainsname
list_usage_recordsList resource usage recordsstartdate, enddate (required), type

šŸ—ļø Infrastructure Discovery (2 Tools)

ToolDescriptionParameters
list_zonesList all available zonesavailable (optional)
list_templatesList available VM templatestemplatefilter, zoneid (optional)

šŸ”§ System Administration (5 Tools)

ToolDescriptionParameters
list_hostsList physical hostszoneid, type, state
list_clustersList host clusterszoneid
list_storage_poolsList storage poolszoneid, clusterid
list_system_vmsList system virtual machineszoneid, systemvmtype
list_service_offeringsList service offeringsname, domainid

šŸ” Security & Compliance (4 Tools)

ToolDescriptionParameters
list_ssh_key_pairsList SSH key pairsname
create_ssh_key_pairCreate a new SSH key pairname (required)
list_security_groupsList security groupssecuritygroupname
create_security_group_ruleCreate a security group ingress rulesecuritygroupid, 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

VariableDescriptionExample
CLOUDSTACK_API_URLCloudStack API endpointhttp://cloudstack.example.com:8080/client/api
CLOUDSTACK_API_KEYCloudStack API keyyour-32-character-api-key
CLOUDSTACK_SECRET_KEYCloudStack secret keyyour-secret-key

Optional Environment Variables

VariableDescriptionDefault
CLOUDSTACK_TIMEOUTRequest 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