phantosmax/cloudstack-mcp-server

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)

⚙️ 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

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

Optional Environment Variables

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