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

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLI.md		CLI.md
LICENSE		LICENSE
README.md		README.md
jest.config.cjs		jest.config.cjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

phantosmax/cloudstack-mcp-server

Folders and files

Latest commit

History

Repository files navigation

CloudStack MCP Server

Features

Quick Start

Installation

MCP Client Integration

Command Line Interface

Available Tools (45 Tools)

🖥️ Virtual Machine Management (7 Tools)

⚙️ VM Advanced Operations (4 Tools)

💾 Storage Management (7 Tools)

🌐 Networking (7 Tools)

📊 Monitoring & Analytics (5 Tools)

👥 Account & User Management (4 Tools)

🏗️ Infrastructure Discovery (2 Tools)

🔧 System Administration (5 Tools)

🔐 Security & Compliance (4 Tools)

Example Usage

List Virtual Machines

Deploy New Virtual Machine

Project Structure

Architecture Overview

Configuration

Required Environment Variables

Optional Environment Variables

Development

Build Commands

Code Quality

Security

Compatibility

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Uh oh!

Languages

Packages