Connect an AI Assistant

Homecast exposes Model Context Protocol (MCP) tools so AI assistants can read and control your smart home through natural language.

How it works

When you connect an AI assistant to Homecast, it gets three tools:

• get_state — Read the current state of your devices
• set_state — Control devices (turn on/off, set brightness, etc.)
• run_scene — Execute HomeKit scenes

The assistant calls these tools behind the scenes when you ask things like "turn off the living room lights" or "what's the temperature in the bedroom?"

Setup for Claude Desktop / Claude Code

Add this to your MCP client configuration:

{
  "mcpServers": {
    "homecast": {
      "type": "url",
      "url": "https://api.homecast.cloud/mcp"
    }
  }
}

On first use, the OAuth flow will open in your browser:

1. Sign in to your Homecast account
2. Choose which homes to grant access to
3. Select the permission level (view for read-only, control for read and write)
4. Approve the connection

The assistant stores its OAuth token and reconnects automatically.

Setup with an access token

If your MCP client doesn't support OAuth, create an access token instead:

1. Go to Settings → API Tokens at homecast.cloud
2. Create a token with the desired home permissions
3. Configure your MCP client with the token as a Bearer header:

{
  "mcpServers": {
    "homecast": {
      "type": "url",
      "url": "https://api.homecast.cloud/mcp",
      "headers": {
        "Authorization": "Bearer hc_your_token_here"
      }
    }
  }
}

Available tools

get_state

Read the current state of your devices. Returns a hierarchical view of homes, rooms, and accessories with their current values.

Parameter	Type	Required	Description
filter_by_home	string	No	Only show devices in this home
filter_by_room	string	No	Only show devices in this room
filter_by_type	string	No	Only show this device type (e.g., lightbulb, thermostat)
filter_by_name	string	No	Only show devices matching this name

set_state

Control one or more devices. Each update specifies a device by home, room, and accessory name, plus the properties to change.

Parameter	Type	Required	Description
updates	array	Yes	List of device updates
updates[].home	string	Yes	Home name
updates[].room	string	Yes	Room name
updates[].accessory	string	Yes	Accessory name
updates[].on	boolean	No	Power state
updates[].brightness	integer	No	Brightness 0–100
updates[].hue	integer	No	Color hue 0–360
updates[].saturation	integer	No	Color saturation 0–100
updates[].color_temp	integer	No	Color temperature (mireds)
updates[].hvac_mode	string	No	HVAC mode: off, heat, cool, auto
updates[].heat_target	float	No	Heating target temperature
updates[].cool_target	float	No	Cooling target temperature
updates[].lock_target	integer	No	1 = lock, 0 = unlock
updates[].speed	integer	No	Fan speed 0–100
updates[].target	integer	No	Position 0–100 (blinds, garage)

run_scene

Execute a HomeKit scene by name.

Parameter	Type	Required	Description
home	string	Yes	Home name
name	string	Yes	Scene name

What you can ask

Once connected, you can use natural language:

• "Turn off the living room lights"
• "Set the bedroom to 72 degrees"
• "What's the temperature in the kitchen?"
• "Lock the front door"
• "Dim the office lights to 30%"
• "Run the Good Night scene"
• "Are any lights on right now?"
• "Set all lights to warm white"
• "Close the garage door"
• "What devices are in the bedroom?"

The AI reads your device state, figures out the right API calls, and executes them.

Security

• Separate tokens per assistant — Create a dedicated token for each AI integration so you can revoke individually
• Review authorized apps — Check Settings → Authorized Apps to see which OAuth clients have access
• Home-scoped permissions — Limit each assistant to specific homes and view or control access
• Revoke access — Remove an authorized app or delete a token at any time from Settings

See the MCP reference for protocol details and the Authentication reference for all auth models.