Homelab MCP Server

Instructions

Implementation Reference

• src/homelab_mcp/proxmox_api.py:453-536 (handler)

  Main implementation of create_proxmox_vm - creates a new QEMU VM on Proxmox with configurable memory, cores, storage, disk size, and optional ISO attachment. Includes logic to start the VM after creation if requested.

  async def create_proxmox_vm(
      node: str,
      vmid: int,
      name: str,
      host: str | None = None,
      memory: int = 2048,
      cores: int = 2,
      sockets: int = 1,
      storage: str = "local-lvm",
      disk_size: int = 32,
      iso: str | None = None,
      cdrom: str | None = None,
      net0: str = "virtio,bridge=vmbr0",
      ostype: str = "l26",
      start: bool = False,
      **kwargs: Any,
  ) -> dict[str, Any]:
      """
      Create a new VM (QEMU).
  
      Args:
          node: Node name
          vmid: VM ID
          name: VM name
          host: Proxmox host (optional)
          memory: RAM in MB
          cores: Number of CPU cores
          sockets: Number of CPU sockets
          storage: Storage for disks
          disk_size: Disk size in GB
          iso: ISO image to attach
          cdrom: CDROM image
          net0: Network configuration
          ostype: OS type
          start: Start after creation
          **kwargs: Additional VM parameters
  
      Returns:
          Creation result
      """
      client = get_proxmox_client(host=host)
  
      try:
          # Build VM config
          config: dict[str, Any] = {
              "vmid": vmid,
              "name": name,
              "memory": memory,
              "cores": cores,
              "sockets": sockets,
              "scsi0": f"{storage}:{disk_size}",
              "net0": net0,
              "ostype": ostype,
          }
  
          if iso:
              config["ide2"] = f"{iso},media=cdrom"
          elif cdrom:
              config["cdrom"] = cdrom
  
          # Add any additional parameters
          config.update(kwargs)
  
          result = await client.post(f"/nodes/{node}/qemu", config)
  
          # Start if requested
          if start and result:
              await manage_proxmox_vm(node, vmid, "start", host, "qemu")
  
          return {
              "status": "success",
              "node": node,
              "vmid": vmid,
              "name": name,
              "message": f"VM {vmid} created successfully",
              "data": result,
          }
  
      except (aiohttp.ClientError, ValueError) as e:
          logger.error("Error creating VM: %s", str(e))
          return {
              "status": "error",
              "message": f"Failed to create VM: {str(e)}",
          }

• src/homelab_mcp/tool_handlers/proxmox_handlers.py:110-124 (handler)

  MCP tool handler wrapper for create_proxmox_vm - parses arguments from the tool call and passes them to the underlying create_proxmox_vm function, then formats the response as JSON content.

  async def handle_create_proxmox_vm(arguments: dict[str, Any]) -> dict[str, Any]:
      """Handle create_proxmox_vm tool."""
      result = await create_proxmox_vm(
          node=arguments["node"],
          vmid=arguments["vmid"],
          name=arguments["name"],
          host=arguments.get("host"),
          memory=arguments.get("memory", 2048),
          cores=arguments.get("cores", 2),
          storage=arguments.get("storage", "local-lvm"),
          disk_size=arguments.get("disk_size", 32),
          iso=arguments.get("iso"),
          start=arguments.get("start", False),
      )
      return {"content": [{"type": "text", "text": json.dumps(result, indent=2)}]}

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

  Tool registration mapping 'create_proxmox_vm' to its handler function handle_create_proxmox_vm in the TOOL_HANDLERS registry.

  "create_proxmox_vm": handle_create_proxmox_vm,

• src/homelab_mcp/tool_schemas/proxmox_tools_schema.py:208-261 (schema)

  Input/output schema definition for create_proxmox_vm tool - defines required parameters (node, vmid, name) and optional parameters (memory, cores, disk_size, storage, iso, start, host) with their types, descriptions, and default values.

  "create_proxmox_vm": {
      "description": "Create a new VM (QEMU) on Proxmox",
      "inputSchema": {
          "type": "object",
          "properties": {
              "node": {
                  "type": "string",
                  "description": "Node name",
              },
              "vmid": {
                  "type": "integer",
                  "description": "VM ID (must be unique)",
              },
              "name": {
                  "type": "string",
                  "description": "VM name",
              },
              "memory": {
                  "type": "integer",
                  "description": "RAM in MB",
                  "default": 2048,
              },
              "cores": {
                  "type": "integer",
                  "description": "Number of CPU cores",
                  "default": 2,
              },
              "disk_size": {
                  "type": "integer",
                  "description": "Disk size in GB",
                  "default": 32,
              },
              "storage": {
                  "type": "string",
                  "description": "Storage for disks",
                  "default": "local-lvm",
              },
              "iso": {
                  "type": "string",
                  "description": "ISO image to attach (e.g., 'local:iso/debian-12.iso')",
              },
              "start": {
                  "type": "boolean",
                  "description": "Start VM after creation",
                  "default": False,
              },
              "host": {
                  "type": "string",
                  "description": "Proxmox host (optional)",
              },
          },
          "required": ["node", "vmid", "name"],
      },
  },

• src/homelab_mcp/proxmox_api.py:155-200 (helper)

  Helper function get_proxmox_client - retrieves or creates a ProxmoxAPIClient instance using credentials from environment variables or parameters, used by create_proxmox_vm to authenticate API requests.

  def get_proxmox_client(
      host: str | None = None,
      port: int = 8006,
      verify_ssl: bool | None = None,
      username: str | None = None,
      password: str | None = None,
      api_token: str | None = None,
  ) -> ProxmoxAPIClient:
      """
      Get a Proxmox API client with credentials from environment or parameters.
  
      Args:
          host: Proxmox host (defaults to PROXMOX_HOST env var)
          port: API port (default: 8006)
          verify_ssl: Verify SSL (defaults to PROXMOX_VERIFY_SSL env var)
          username: Username (defaults to PROXMOX_USER env var)
          password: Password (defaults to PROXMOX_PASSWORD env var)
          api_token: API token (defaults to PROXMOX_API_TOKEN env var)
  
      Returns:
          Configured ProxmoxAPIClient instance
      """
      # Get from environment if not provided
      host = host or os.getenv("PROXMOX_HOST")
      if not host:
          raise ValueError("Proxmox host must be provided or set in PROXMOX_HOST env var")
  
      if verify_ssl is None:
          verify_ssl = os.getenv("PROXMOX_VERIFY_SSL", "false").lower() == "true"
  
      username = username or os.getenv("PROXMOX_USER")
      password = password or os.getenv("PROXMOX_PASSWORD")
      api_token = api_token or os.getenv("PROXMOX_API_TOKEN")
  
      # Must have either API token or username+password
      if not api_token and not (username and password):
          raise ValueError("Must provide either PROXMOX_API_TOKEN or PROXMOX_USER+PROXMOX_PASSWORD")
  
      return ProxmoxAPIClient(
          host=host,
          port=port,
          verify_ssl=verify_ssl,
          username=username,
          password=password,
          api_token=api_token,
      )