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

Clone and install dependencies:
git clone <repository-url> cd cloudstack-mcp-server npm install
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
Build the project:
npm run build
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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

A high-performance server that enables integration between Apache CloudStack infrastructure and AI assistants through the Model Context Protocol, providing comprehensive tools for managing virtual machines, storage, networking, and other cloud resources.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MCP Personal Assistant Agent
zhangzhongnan928
-
security
F
license
-
quality
A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
18
MCP Server with Cloudflare Workers
sivakumarl
-
security
F
license
-
quality
An open standard server implementation that enables AI assistants to directly access APIs and services through Model Context Protocol, built using Cloudflare Workers for scalability.
Last updated -
MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
33
1
MCP SysOperator
tarnover
A
security
A
license
A
quality
A Model Context Protocol server enabling AI assistants to directly interact with infrastructure tools like Ansible and Terraform for executing playbooks, managing cloud resources, and performing other infrastructure operations.
Last updated -
18
14
MIT License

View all related MCP servers

Appeared in Searches

Cloud Infrastructure Management and Deployment Tools for Oracle Cloud and A2A Communication