Home Assistant MCP

Instructions

Args:
    entity_id: The Home Assistant entity ID to control (format: light.entity)
    red: Red component (0-255)
    green: Green component (0-255)
    blue: Blue component (0-255)
    brightness: Optional brightness level (0-255)

Implementation Reference

• app/tools/device_controls.py:52-87 (handler)

  The handler function that validates inputs and calls the Home Assistant API to set RGB color and optional brightness on a light entity.

  async def set_device_color(entity_id: str, red: int, green: int, blue: int, brightness: int = None) -> str:
      """Set the color and optionally brightness of a light entity.
      
      Args:
          entity_id: The Home Assistant entity ID to control (format: light.entity)
          red: Red component (0-255)
          green: Green component (0-255)
          blue: Blue component (0-255)
          brightness: Optional brightness level (0-255)
      """
      # Basic validation
      if not entity_id or not entity_id.startswith("light."):
          return f"Invalid entity ID format: {entity_id}. Must be a light entity (format: light.entity)"
      
      # Validate RGB values
      for color, name in [(red, "Red"), (green, "Green"), (blue, "Blue")]:
          if not 0 <= color <= 255:
              return f"Invalid {name} value: {color}. Must be between 0 and 255"
      
      # Validate brightness if provided
      if brightness is not None and not 0 <= brightness <= 255:
          return f"Invalid brightness value: {brightness}. Must be between 0 and 255"
      
      # Check token
      if not HOME_ASSISTANT_TOKEN:
          return "Home Assistant token not configured. Set HOME_ASSISTANT_TOKEN environment variable."
      
      # Call the HA API
      result = await set_light_color(entity_id, [red, green, blue], brightness)
      
      if result["success"]:
          color_msg = f"color to RGB({red},{green},{blue})"
          brightness_msg = f" and brightness to {brightness}" if brightness is not None else ""
          return f"Successfully set {entity_id} {color_msg}{brightness_msg}"
      else:
          return f"Failed to set color for {entity_id}: {result.get('error', 'Unknown error')}"

• app/tools/device_controls.py:11-20 (registration)

  Registers the set_device_color tool (and others) with the FastMCP instance.

  def init_tools(fastmcp_instance: FastMCP):
      """Initialize the tools with a FastMCP instance."""
      global mcp
      mcp = fastmcp_instance
      
      # Register tools with the FastMCP instance
      fastmcp_instance.tool()(control_device)
      fastmcp_instance.tool()(search_entities)
      fastmcp_instance.tool()(set_device_color)  # Register set_device_color like other tools