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