CloudStack

You deploy this CloudStack MCP Server to manage CloudStack infrastructure through the MCP protocol, enabling seamless automation, AI-assisted operations, and programmable VM, network, and storage management with full type safety and robust error handling.

How to use

You connect a compatible MCP client to the CloudStack MCP Server to perform VM lifecycle actions, discovery, and management tasks. Start by configuring the client to run the MCP server locally or remotely, using the provided stdio integration. The server exposes a wide range of tools for VM operations, storage, networking, monitoring, accounts, infrastructure discovery, and system administration. You can drive actions such as deploying VMs, starting or stopping them, scaling resources, migrating VMs, managing volumes and snapshots, and inspecting zones, templates, and service offerings. All requests are signed and validated, and errors are sanitized to avoid leaking sensitive data.

Typical workflows include starting the MCP server in your environment, pointing your MCP client to the server, and then issuing high‑level intents (for example, deploy a VM or list available zones). You will observe rich VM metadata, secure authentication via HMAC-SHA1 with your CloudStack credentials, and a high‑performance TypeScript implementation that preserves type safety across all tool handlers.

How to install

Prerequisites you need before installing include a supported Node.js runtime and a compatible MCP client environment. The server is built with TypeScript and targets Node.js 18+ for optimal compatibility and performance.

# 1. Clone the project repository
git clone <repository-url>
cd cloudstack-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment variables (example values shown)
# CLOUDSTACK_API_URL=https://your-cloudstack-server/client/api
# CLOUDSTACK_API_KEY=your-api-key
# CLOUDSTACK_SECRET_KEY=your-secret-key
# CLOUDSTACK_TIMEOUT=30000

# 4. Build the project
npm run build

# 5. Run the server in development mode (MCP server)
npm run dev

# 6. Run the server in production mode (MCP server)
npm start

# 7. Access the CLI for direct CloudStack management via the MCP server
npm run cli -- --help

Additional setup and configuration

Configure environment variables in your runtime environment to enable CloudStack API access. The required variables include the API URL, API key, and secret key. An optional timeout value controls request latency. These settings are read at startup by the MCP server and used for all subsequent MCP interactions.

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

Connection to the MCP client (stdio mode)

If you want to run the MCP server locally and connect from an MCP client, you can start the server using the stdio approach. The client launches the server as a local process and communicates via standard input and output.

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

Security and maintenance notes

The server uses HMAC-SHA1 signing for all API requests and does not store credentials. Credentials are read only from environment variables at runtime. Input validation and error sanitization are applied to all tool parameters and responses to prevent leakage of sensitive information.

Ensure your CloudStack CloudStack API version compatibility (4.11+ is supported) and run the server with Node.js 18+ for best results. Regularly update dependencies and rebuild to benefit from security fixes and feature improvements.

Troubleshooting tips

If you encounter network or authentication errors, verify that CLOUDSTACK_API_URL, CLOUDSTACK_API_KEY, and CLOUDSTACK_SECRET_KEY are correctly set in your environment and that the CloudStack API endpoint is reachable from the host running the MCP server.

Check that the build artifacts exist at the configured path (for stdio mode) and that the server process has the necessary permissions to read environment variables and access the CloudStack API.

Examples of common usage patterns

Deploy a new VM, list available zones, and inspect VM metadata are typical actions you can automate through your MCP client. Use the 45+ tool handlers to perform lifecycle operations, manage storage and networks, monitor resources, and perform infrastructure discovery.

Project structure overview

The server is organized to separate concerns between the MCP entry point, the MCP server implementation, the command-line interface, and the CloudStack API client. This modular design supports easy maintenance and clear extension points for additional tools.

Example usage flow for deploying and managing VMs

You can deploy a new VM using the MCP client and then query its status to confirm successful creation. After deployment, you can start, stop, reboot, or scale the VM as needed, and you can attach volumes or modify networking configurations through the corresponding tools.

Available tools

list_virtual_machines

List VMs with optional filtering such as zone, state, or keyword.

get_virtual_machine

Retrieve detailed information for a specific VM by its ID.

start_virtual_machine

Start a stopped virtual machine by its ID.

stop_virtual_machine

Stop a running virtual machine by its ID, with an optional forced stop.

reboot_virtual_machine

Reboot a VM by its ID.

destroy_virtual_machine

Destroy a VM with a proper workflow, requiring confirmation and optional expunge.

deploy_virtual_machine

Deploy a new VM with a chosen service offering, template, and zone, optionally specifying network IDs and display names.

scale_virtual_machine

Resize a VM by changing its service offering.

migrate_virtual_machine

Migrate a VM to another host, with an optional host target.

reset_password_virtual_machine

Reset the password for a VM.

change_service_offering_virtual_machine

Change the service offering of a VM.

list_volumes

List storage volumes with optional filters like VM, type, and zone.

create_volume

Create a new storage volume in a specified zone.

attach_volume

Attach a storage volume to a VM.

detach_volume

Detach a volume from a VM, with optional confirmation.

resize_volume

Resize a storage volume with confirmation.

create_snapshot

Create a snapshot of a volume.

list_snapshots

List volume snapshots with optional filters.

list_networks

List networks in a zone with optional type.

create_network

Create a new network in a zone.

list_public_ip_addresses

List public IP addresses in a zone or associated network.

associate_ip_address

Acquire a new public IP address in a zone.

enable_static_nat

Enable static NAT for a specific IP and VM.

create_firewall_rule

Create a firewall rule for a given IP address.

list_load_balancer_rules

List load balancer rules for a public IP in a zone.

list_virtual_machine_metrics

Get performance metrics for one or more VMs.

list_events

List CloudStack events with filters such as type and date.

list_alerts

List system alerts by type.

list_capacity

List system capacity information for a zone.

list_async_jobs

List asynchronous CloudStack jobs by status.

list_accounts

List CloudStack accounts within a domain.

list_users

List users within an account.

list_domains

List CloudStack domains.

list_usage_records

List resource usage records within a date range and type.

list_zones

List all available zones.

list_templates

List VM templates with optional filters.

list_hosts

List physical hosts with zone, type, and state filters.

list_clusters

List host clusters within a zone.

list_storage_pools

List storage pools in a zone or cluster.

list_system_vms

List system virtual machines filtered by zone and type.

list_service_offerings

List service offerings by name or domain.

list_ssh_key_pairs

List SSH key pairs by name.

create_ssh_key_pair

Create a new SSH key pair by name.

list_security_groups

List security groups by name.

create_security_group_rule

Create an ingress rule for a security group with protocol, ports, and CIDR.