Cloudstack MCP Server

🚀 CloudStack MCP Server

A high-performance MCP (Model Context Protocol) server for Apache CloudStack API integration, enabling seamless interaction with AI assistants and automation tools.

🚀 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 CLI.md.

✨ 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

💻 Usage Examples

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

📚 Documentation

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)

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

🔧 Technical Details

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