cloud-vm-mcp-py 0.5.0

A Model Context Protocol for managing and viewing virtual machines across multiple cloud providers (AWS, Azure, Alibaba Cloud)

Cloud VM MCP: Model Context Protocol for Cloud VM Management

Cloud VM MCP is a Model Context Protocol (MCP) server for managing and viewing virtual machines across multiple cloud providers (AWS, Azure, Alibaba Cloud). It enables AI assistants to list, inspect, and control VMs through a unified interface.

---

Installation 📦

# Install from PyPI
pip install cloud-vm-mcp-py

# Or using uv
uv add cloud-vm-mcp-py

---

Usage Guide 📖

VM MCP can be used in two ways: as an MCP server or as a direct command-line tool.

MCP Server Usage

Start the MCP server:

uv run vm-mcp

Available MCP Tools:

1. list_vms: List all VMs across configured providers

   • Parameters: provider (optional), tenant (optional), region (optional)

2. list_providers: List all configured cloud providers

   • Parameters: None

3. get_vm_details: Get detailed information about a specific VM

   • Parameters: vm_id (composite ID format: provider:tenant:region:instance)

4. start_vm: Start a virtual machine

   • Parameters: vm_id

5. stop_vm: Stop a virtual machine

   • Parameters: vm_id, force (optional, default: false)

Integration with Claude Desktop

To use Cloud VM MCP with Claude Desktop, add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "vm": {
      "command": "uvx",
      "args": ["cloud-vm-mcp-py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PROVIDERS_CONFIG_PATH": "/path/to/your/providers.yaml"
      }
    }
  }
}

Configuration File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Direct Command-Line Usage

You can manage VMs directly using the CLI:

List all VMs:

PROVIDERS_CONFIG_PATH=./providers.yaml uv run python cli.py list

Filter by provider/tenant/region:

uv run python cli.py list --provider aws --tenant production --region us-east-1

Get VM details:

uv run python cli.py info aws:production:us-east-1:i-1234567890abcdef0

Start/Stop VMs:

uv run python cli.py start aws:production:us-east-1:i-1234567890abcdef0
uv run python cli.py stop azure:corp-main:eastus:web-server --force

List configured providers:

uv run python cli.py providers

MCP Inspector

You can inspect and test the MCP server using the MCP Inspector:

npx @modelcontextprotocol/inspector uv run vm-mcp -e PROVIDERS_CONFIG_PATH=/path/to/providers.yaml

---

Key Features 🚀

• Multi-Provider Support: Manage VMs across AWS, Azure, and Alibaba Cloud from a single interface
• Multi-Account Support: Configure multiple AWS accounts and Azure directories
• Unified VM Model: Consistent VM representation across providers
• Filtering: Filter VMs by provider, tenant (account/directory), or region
• Power Management: Start and stop VMs with optional force flag
• Hot-Reload: Configuration changes are automatically detected and applied
• MCP Integration: Provides tools for AI assistants through the Model Context Protocol

---

Requirements 📋

• Python 3.10 or higher
• boto3: For AWS EC2 operations
• azure-identity, azure-mgmt-compute, azure-mgmt-network: For Azure VM operations
• alibabacloud-ecs20140526, alibabacloud-tea-openapi: For Alibaba Cloud ECS operations
• pyyaml: For YAML configuration parsing
• watchdog: For configuration file watching

---

Configuration ⚙️

Cloud VM MCP uses a YAML configuration file to define cloud provider credentials. Set the PROVIDERS_CONFIG_PATH environment variable to point to your configuration file.

Configuration File Setup

Create a providers.yaml file with your provider credentials:

Example providers.yaml:

providers:
  aws:
    accounts:
      - alias: production
        access_key_id: AKIAIOSFODNN7EXAMPLE
        secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
        regions:
          - us-east-1
          - us-west-2

      - alias: staging
        access_key_id: AKIAI44QH8DHBEXAMPLE
        secret_access_key: je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
        regions:
          - us-east-1

  azure:
    directories:
      - alias: corp-main
        tenant_id: 00000000-0000-0000-0000-000000000000
        client_id: 11111111-1111-1111-1111-111111111111
        client_secret: your-client-secret-here
        subscription_ids:
          - 22222222-2222-2222-2222-222222222222

  alibaba:
    accounts:
      - alias: china-prod
        access_key_id: LTAI5tYourAccessKeyId
        access_key_secret: YourAccessKeySecret
        regions:
          - cn-hangzhou
          - ap-southeast-1

Environment Variables

• MCP_TRANSPORT: stdio, sse, streamable-http (defaults to stdio)
• PROVIDERS_CONFIG_PATH: Path to YAML configuration file (required)
• VM_MCP_CONFIRM_REQUIRED_TOOLS: Comma-separated tool names that require user confirmation before running (defaults to start_vm,stop_vm,reboot_vm). The confirmation prompt is sent via the MCP elicitation protocol, so it appears only in clients that support elicitation (e.g. Claude Code, MCP Inspector); other clients run the tool unprompted. Set to an empty value to disable confirmation for all tools.

Security Recommendations

• Store the configuration file with restricted permissions (chmod 600 providers.yaml)
• Never commit credentials to version control
• Consider using environment variables for sensitive values in production

---

VM Identifier Format 🔖

VMs are identified using a composite ID format:

{provider}:{tenant_alias}:{region}:{instance_id}

Examples:

• AWS: aws:production:us-east-1:i-1234567890abcdef0
• Azure: azure:corp-main:eastus:web-server-01
• Alibaba: alibaba:china-prod:cn-hangzhou:i-bp1234567890abcdef

---

Timeout Configuration ⏱️

• Per-request timeout: 60 seconds
• Total query timeout: 180 seconds (3 minutes) for multi-provider queries

---

Development & Testing 🧪

Setup

1. Clone the repository
2. Install dependencies: uv sync
3. Setup pre-commit: uv run pre-commit install

Running Tests

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=vm_mcp --cov-report=html

Code Quality

uv run ruff check .
uv run ruff format .

Publishing to PyPI

rm -rf dist
uv build
uv publish --username __token__ --password YOUR_PYPI_API_KEY

---

Future Roadmap 🗺️

• Firewall rules viewing
• Elastic IP management
• RAM/CPU/GPU details
• Scheduled start/stop operations

---

License

MIT License - See LICENSE for details.