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.
- π§ 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
-
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
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"
}
}
}
}
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.
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) |
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) |
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 |
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 |
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 |
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 |
Tool | Description | Parameters |
---|---|---|
list_zones |
List all available zones | available (optional) |
list_templates |
List available VM templates | templatefilter , zoneid (optional) |
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 |
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 |
{
"tool": "list_virtual_machines",
"arguments": {
"state": "Running",
"zoneid": "1746ef10-8fa6-40c1-9c82-c3956bf75db8"
}
}
{
"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"
}
}
βββ 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)
src/index.ts
: MCP server entry point that loads environment variables and starts the serversrc/server.ts
: Comprehensive MCP server implementation with 45+ tool handlers, error management, and CloudStack integrationsrc/cli.ts
: Command-line interface for direct CloudStack management via JSON-RPC communication with the MCP serversrc/cloudstack-client.ts
: Robust CloudStack API client with HMAC-SHA1 authentication, type-safe interfaces, and comprehensive error handling
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 |
Variable | Description | Default |
---|---|---|
CLOUDSTACK_TIMEOUT |
Request timeout (milliseconds) | 30000 |
# 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
- 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
- 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
- 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+
MIT - See LICENSE file for details