Homelab MCP Server

Instructions

Implementation Reference

• src/homelab_mcp/proxmox_api.py:593-642 (handler)

  Core implementation of delete_proxmox_vm that stops the VM/container if running, then deletes it via Proxmox API. Supports both VMs (qemu) and containers (lxc), with optional purge to remove from all related configurations.

  async def delete_proxmox_vm(
      node: str,
      vmid: int,
      host: str | None = None,
      vm_type: str = "qemu",
      purge: bool = False,
  ) -> dict[str, Any]:
      """
      Delete a VM or container.
  
      Args:
          node: Node name
          vmid: VM/Container ID
          host: Proxmox host (optional)
          vm_type: 'qemu' for VM or 'lxc' for container
          purge: Remove from all related configurations
  
      Returns:
          Deletion result
      """
      client = get_proxmox_client(host=host)
  
      try:
          # Stop VM first if running
          try:
              await manage_proxmox_vm(node, vmid, "stop", host, vm_type)
          except Exception:
              pass  # VM might already be stopped
  
          # Delete
          endpoint = f"/nodes/{node}/{vm_type}/{vmid}"
          if purge:
              endpoint += "?purge=1"
  
          result = await client.delete(endpoint)
  
          return {
              "status": "success",
              "node": node,
              "vmid": vmid,
              "message": f"VM {vmid} deleted successfully",
              "data": result,
          }
  
      except (aiohttp.ClientError, ValueError) as e:
          logger.error("Error deleting VM: %s", str(e))
          return {
              "status": "error",
              "message": f"Failed to delete VM: {str(e)}",
          }

• src/homelab_mcp/tool_handlers/proxmox_handlers.py:141-150 (handler)

  MCP tool handler wrapper that extracts arguments from the tool call and invokes the delete_proxmox_vm function, returning the result in MCP protocol format.

  async def handle_delete_proxmox_vm(arguments: dict[str, Any]) -> dict[str, Any]:
      """Handle delete_proxmox_vm tool."""
      result = await delete_proxmox_vm(
          node=arguments["node"],
          vmid=arguments["vmid"],
          host=arguments.get("host"),
          vm_type=arguments.get("vm_type", "qemu"),
          purge=arguments.get("purge", False),
      )
      return {"content": [{"type": "text", "text": json.dumps(result, indent=2)}]}

• src/homelab_mcp/tool_handlers/__init__.py:130-130 (registration)

  Tool registration mapping 'delete_proxmox_vm' to its handler function in the tool handlers registry.

  "delete_proxmox_vm": handle_delete_proxmox_vm,

• src/homelab_mcp/tool_schemas/proxmox_tools_schema.py:302-333 (schema)

  Schema definition for delete_proxmox_vm tool, specifying input parameters (node, vmid, vm_type, purge, host) with types, descriptions, defaults, and required fields.

  "delete_proxmox_vm": {
      "description": "Delete a VM or container from Proxmox",
      "inputSchema": {
          "type": "object",
          "properties": {
              "node": {
                  "type": "string",
                  "description": "Node name",
              },
              "vmid": {
                  "type": "integer",
                  "description": "VM/Container ID to delete",
              },
              "vm_type": {
                  "type": "string",
                  "description": "Type: 'qemu' for VM or 'lxc' for container",
                  "enum": ["qemu", "lxc"],
                  "default": "qemu",
              },
              "purge": {
                  "type": "boolean",
                  "description": "Remove from all related configurations",
                  "default": False,
              },
              "host": {
                  "type": "string",
                  "description": "Proxmox host (optional)",
              },
          },
          "required": ["node", "vmid"],
      },
  },