Hue MCP Server

Instructions

Implementation Reference

• main.py:48-127 (handler)

  The main handler function for the 'change_hue_light' tool. It connects to the Philips Hue Bridge, validates input parameters, constructs a command dictionary based on provided arguments (light_id, brightness, hue, saturation, on), and updates the light's state accordingly. Returns success or error messages.
  def change_hue_light( light_id: int, brightness: Optional[int] = None, hue: Optional[int] = None, saturation: Optional[int] = None, on: Optional[bool] = None ) -> str: """ Change the state of a Philips Hue light. Args: light_id: The ID of the light to control (1-based index) brightness: Brightness level (0-254), where 0 is minimum and 254 is maximum hue: Hue color value (0-65535), where 0 and 65535 are red, 25500 is green, and 46920 is blue saturation: Color saturation (0-254), where 0 is white and 254 is most saturated on: Turn the light on (True) or off (False) Returns: A message indicating the result of the operation """ try: bridge = get_bridge() # Verify we have lights if not bridge.lights: return "Error: No lights found on the Hue Bridge. Please check your bridge connection." # Get the light (phue uses 1-based indexing) if light_id < 1 or light_id > len(bridge.lights): return f"Error: Light ID {light_id} is out of range. Available lights: 1-{len(bridge.lights)}" light = bridge.lights[light_id - 1] # Build the command dictionary command = {} if on is not None: command['on'] = on if brightness is not None: if not 0 <= brightness <= 254: return f"Error: Brightness must be between 0 and 254, got {brightness}" command['bri'] = brightness if hue is not None: if not 0 <= hue <= 65535: return f"Error: Hue must be between 0 and 65535, got {hue}" command['hue'] = hue if saturation is not None: if not 0 <= saturation <= 254: return f"Error: Saturation must be between 0 and 254, got {saturation}" command['sat'] = saturation # Apply the command if command: # Use the light's state property to set multiple values at once for key, value in command.items(): setattr(light, key, value) status_parts = [] if 'on' in command: status_parts.append(f"turned {'on' if command['on'] else 'off'}") if 'bri' in command: status_parts.append(f"brightness set to {command['bri']}") if 'hue' in command: status_parts.append(f"hue set to {command['hue']}") if 'sat' in command: status_parts.append(f"saturation set to {command['sat']}") return f"Successfully updated light {light_id} ({light.name}): {', '.join(status_parts)}" else: return f"No changes specified for light {light_id} ({light.name})" except ValueError as e: return f"Configuration error: {str(e)}" except IndexError: return f"Error: Light {light_id} not found. Please check the light ID." except Exception as e: return f"Error controlling light: {str(e)}"
• main.py:47-47 (registration)

  The @mcp.tool() decorator registers the change_hue_light function as an MCP tool with FastMCP server.
  @mcp.tool()
• main.py:48-67 (schema)

  Function signature and docstring define the tool schema: parameters light_id (int), brightness (Optional[int]), hue (Optional[int]), saturation (Optional[int]), on (Optional[bool]), with ranges and descriptions.
  def change_hue_light( light_id: int, brightness: Optional[int] = None, hue: Optional[int] = None, saturation: Optional[int] = None, on: Optional[bool] = None ) -> str: """ Change the state of a Philips Hue light. Args: light_id: The ID of the light to control (1-based index) brightness: Brightness level (0-254), where 0 is minimum and 254 is maximum hue: Hue color value (0-65535), where 0 and 65535 are red, 25500 is green, and 46920 is blue saturation: Color saturation (0-254), where 0 is white and 254 is most saturated on: Turn the light on (True) or off (False) Returns: A message indicating the result of the operation """
• main.py:30-44 (helper)

  get_bridge() utility caches and returns the phue Bridge instance, initialized from HUE_BRIDGE_IP env var.
  def get_bridge() -> Bridge: """Get or initialize the Hue Bridge connection.""" global _bridge_instance if not BRIDGE_IP: raise ValueError( "HUE_BRIDGE_IP environment variable not set. " "Please set it to your Hue Bridge IP address." ) # Reuse existing connection or create new one if _bridge_instance is None: _bridge_instance = Bridge(BRIDGE_IP) return _bridge_instance