Skip to main content
Glama
sondt2709

Cloud VM MCP

by sondt2709
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

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

Related MCP server: MCP Cloud Services Server

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.

Available Tools

6 tools
get_vm_detailsA

Get detailed information about a specific virtual machine.

Args:
    vm_id: The composite VM ID (format: provider:tenant:region:instance_id)

Returns:
    YAML formatted string containing VM details or error information
ParametersJSON Schema
NameRequiredDescriptionDefault
vm_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility. It states the return format (YAML string containing details or error) and specifies the vm_id format, implying a read-only, idempotent operation. It could be improved by explicitly noting no side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two short sections. The first sentence immediately states the purpose, followed by parameter and return details. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter and an output schema (though not shown), the description covers parameter usage and return type. It lacks error condition details, but for a simple get tool, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description adds significant meaning by explaining the vm_id composite format ('provider:tenant:region:instance_id'). This helps an agent correctly construct the parameter beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the function: 'Get detailed information about a specific virtual machine.' The verb 'get' and noun 'details' precisely indicate a read operation, distinguishing it from sibling tools like list_vms (list all) or start_vm (mutate).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies that the tool retrieves details for one VM. While it doesn't explicitly state when not to use it, the sibling context (list_providers, list_vms, etc.) provides implicit guidance. A brief mention of alternatives would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_providersA

List all configured cloud providers and their accounts/directories.

Returns:
    YAML formatted string containing provider information
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only mentions output format (YAML string) but reveals no side effects, authentication needs, or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Front-loaded with action and outcome. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list tool with an output schema, the description is mostly complete. Could be more specific about 'provider information' but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. Baseline for 0 params is 4. Description adds nothing beyond schema, which is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all configured cloud providers and their accounts/directories,' using a specific verb and resource. It distinguishes from sibling tools which focus on VMs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The context implies it is for listing providers, distinct from VM operations, but lacks direct usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_vmsA

List all virtual machines across configured cloud providers.

Args:
    provider: Optional filter by provider ('aws' or 'azure')
    tenant: Optional filter by tenant alias (AWS account alias or Azure directory alias)
    region: Optional filter by cloud region (e.g., 'us-east-1', 'eastus')

Returns:
    YAML formatted string containing VM list or error information
ParametersJSON Schema
NameRequiredDescriptionDefault
providerNo
tenantNo
regionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It states the tool lists VMs and returns a YAML string, but lacks details on behavior when no filters are given (implies all VMs), performance, pagination, or permissions. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear header and structured Args/Returns sections. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no required parameters and an existing output schema, the description covers the tool's purpose, filters, and return format. Missing details like default behavior (list all VMs) are minor but don't hinder understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no parameter descriptions in schema). The description adds meaning for all three parameters: provider filters by 'aws' or 'azure', tenant by alias, region with examples. This compensates well, though it could specify case sensitivity or invalid values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all virtual machines across configured cloud providers,' which is a specific verb and resource. It differentiates from siblings like get_vm_details (details of a specific VM) and list_providers (list providers), making its purpose distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions optional filters but does not explicitly state when to use this tool versus alternatives (e.g., when to use get_vm_details instead). The context of sibling tools provides implicit guidance, but no direct comparison or when-not-to-use advice is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reboot_vmA

Reboot a virtual machine.

Args:
    vm_id: The composite VM ID (format: provider:tenant:region:instance_id)

Returns:
    YAML formatted string indicating success or failure
ParametersJSON Schema
NameRequiredDescriptionDefault
vm_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states the action but does not disclose side effects (e.g., downtime), required permissions, or behavior if VM is already stopped.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus structured args/returns, no fluff, front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequately covers param format and return, but lacks preconditions (e.g., VM must be running), error handling, and permission context, which are important for a disruptive action.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description compensates by specifying the composite VM ID format: 'provider:tenant:region:instance_id', which adds critical context beyond the schema's bare type field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Reboot a virtual machine' and distinguishes it from sibling tools like start_vm and stop_vm by focusing on restarting an already running VM.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for restarting a VM but provides no explicit guidance on when to choose reboot over start/stop, nor when not to use it (e.g., when VM is off).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_vmA

Start a virtual machine.

Args:
    vm_id: The composite VM ID (format: provider:tenant:region:instance_id)

Returns:
    YAML formatted string indicating success or failure
ParametersJSON Schema
NameRequiredDescriptionDefault
vm_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It states it starts a VM and returns a YAML success/failure string. However, it lacks details like prerequisites (VM must be stopped), permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with no extraneous words. The purpose is front-loaded, and the format follows a clear Args/Returns structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple one-parameter tool and presence of an output schema, the description covers the essential input format and return type. It could benefit from mentioning any preconditions (e.g., VM must be in stopped state), but it is largely adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for the single parameter. The description adds value by specifying the required format 'provider:tenant:region:instance_id', which is critical for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Start a virtual machine' – a specific verb and resource. It distinguishes from siblings like stop_vm and reboot_vm, providing unique purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives (e.g., reboot_vm or stop_vm). The purpose is implied by the name and context, but no direct guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stop_vmA

Stop a virtual machine.

Args:
    vm_id: The composite VM ID (format: provider:tenant:region:instance_id)
    force: Force stop without graceful shutdown (default: False)

Returns:
    YAML formatted string indicating success or failure
ParametersJSON Schema
NameRequiredDescriptionDefault
vm_idYes
forceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It mentions the force option and its effect (force stop without graceful shutdown) but does not disclose potential data loss, permission requirements, or whether the operation is reversible. Some behavioral context is present, but gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with only three sentences for the main description plus an Args/Returns section. It is front-loaded with the core purpose. However, the structure could be slightly improved with clearer separation of lines.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two parameters, no enums, minimal output), the description covers the key points: purpose, parameter details, and return format. It could mention prerequisites (e.g., VM must exist) or side effects, but overall it is sufficient for a basic operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds meaning beyond the schema by specifying the format for vm_id (provider:tenant:region:instance_id) and explaining the force parameter's default and effect. This helps an agent understand parameter usage beyond type constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Stop a virtual machine,' which is a specific verb-resource pair. It distinguishes the tool from sibling tools like start_vm and reboot_vm, as stopping is a distinct operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (to stop a VM) but does not provide explicit guidance on when to use force vs. graceful stop, nor does it differentiate from alternatives like reboot_vm or start_vm. Missing context for usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.4.0
    • First observedget_vm_details
    • First observedlist_providers
    • First observedlist_vms
    • First observedreboot_vm
    • First observedstart_vm
    • First observedstop_vm
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a unique and clearly distinct purpose: listing providers, listing VMs, getting VM details, and power operations (start, stop, reboot). There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_vm_details, start_vm). No mixing of naming conventions.

Tool Count5/5

Six tools is a well-scoped set for managing virtual machines, covering essential listing, details, and power actions without being excessive or insufficient.

Completeness3/5

The set covers listing, details, and power operations but lacks create, delete, or modify VM capabilities, which are notable gaps for full lifecycle management.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sondt2709/cloud-vm-mcp-py'

If you have feedback or need assistance with the MCP directory API, please join our Discord server