Loxone MCP Server

Instructions

Implementation Reference

• src/loxone_mcp/simple_server.py:62-180 (handler)

  The 'loxone_list_devices' function, decorated by '@mcp.tool()', serves as the handler for listing Loxone devices. It connects to the Loxone Miniserver, fetches the structure, and applies optional filters (device_type, room) before returning the device list.

  async def loxone_list_devices(
      host: str | None = None,
      username: str | None = None,
      password: str | None = None,
      port: int = 80,
      client_id: str = "default",
      device_type: str | None = None,
      room: str | None = None,
  ) -> dict[str, Any]:
      """
      List all Loxone devices with optional filtering.
  
      Args:
          host: Loxone Miniserver host/IP address (uses LOXONE_HOST env var if not provided)
          username: Loxone username (uses LOXONE_USERNAME env var if not provided)
          password: Loxone password (uses LOXONE_PASSWORD env var if not provided)
          port: Loxone port (uses LOXONE_PORT env var or default: 80)
          client_id: Unique identifier for the client (default: "default")
          device_type: Filter by device type (e.g., "Switch", "Dimmer", "Jalousie")
          room: Filter by room name
  
      Returns:
          Standardized response with list of devices and their basic information
      """
  
      try:
          # Import here to avoid import issues when running as script
          import sys
          from pathlib import Path
  
          # Add the parent directory to path for imports
          parent_dir = Path(__file__).parent
          if str(parent_dir) not in sys.path:
              sys.path.insert(0, str(parent_dir))
  
          from .config import LoxoneConfig
          from .loxone_client import LoxoneClient
          from .device_manager import DeviceManager
  
          # Use environment variables as primary source, parameters as override
          try:
              if not all([host, username, password]):
                  # Load from environment
                  env_config = LoxoneConfig.from_env()
                  host = host or env_config.host
                  username = username or env_config.username
                  password = password or env_config.password
                  port = port if port != 80 else env_config.port
          except ValueError as e:
              return {
                  "success": False,
                  "error": f"Configuration error: {e}",
                  "error_code": "MISSING_PARAMETERS",
              }
  
          logger.info(f"Listing devices for client {client_id} connecting to {host}:{port}")
  
          # Create configuration
          config = LoxoneConfig(host=host, username=username, password=password, port=port)
  
          # Create and connect client
          client = LoxoneClient(config)
  
          logger.info(f"Connecting to Loxone Miniserver at {host}:{port}...")
          connected = await client.connect()
  
          if not connected:
              return {
                  "success": False,
                  "error": f"Failed to connect to Loxone Miniserver at {host}:{port}",
                  "error_code": "CONNECTION_FAILED",
              }
  
          try:
              # Get structure data
              logger.info("Fetching device structure...")
              structure = await client.get_structure()
  
              # Create device manager and load structure
              device_manager = DeviceManager()
              device_manager.load_devices(structure)
  
              # Get devices with filtering
              devices = device_manager.list_devices(device_type=device_type, room=room)
  
              # Format device information
              device_list = []
              for device in devices:
                  device_info = {
                      "uuid": device.uuid,
                      "name": device.name,
                      "type": device.type,
                      "room": device.room,
                      "category": device.category,
                  }
                  device_list.append(device_info)
  
              logger.info(f"Successfully listed {len(device_list)} devices")
  
              return {
                  "success": True,
                  "devices": device_list,
                  "count": len(device_list),
                  "filters_applied": {"device_type": device_type, "room": room},
              }
  
          finally:
              # Always disconnect
              await client.disconnect()
  
      except Exception as e:
          logger.error(f"Error listing devices: {e}", exc_info=True)
          return {
              "success": False,
              "error": f"Unexpected error: {str(e)}",
              "error_code": "COMMAND_FAILED",
          }