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 these tools:

• get_state — Read the current state of your devices
• set_state — Control devices (turn on/off, set brightness, etc.)
• run_scene / create_scene / update_scene / delete_scene — Execute and manage HomeKit scenes
• get_automations — List your HomeKit automations
• create_automation / update_automation / delete_automation — Build and manage HomeKit automations

The assistant calls these tools behind the scenes when you ask things like "turn off the living room lights" or "turn the porch light on at sunset every day".

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

You can also find the MCP endpoint in the Share dialog for any home — under AI Assistants.

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

1. Enable Developer Mode in Settings → Account at homecast.cloud
2. Go to Settings → API Access → Manage
3. Create a token with the desired home permissions
4. 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

Automation tools

Assistants can also view and manage your HomeKit automations — the same ones you see in the Apple Home app:

• get_automations — Lists automations per home, including whether each is enabled and editable
• create_automation — Creates an automation from a trigger (time of day, sunrise/sunset, a device changing state, or a repeating interval), optional conditions, and device actions
• update_automation — Renames, enables/disables, or modifies an automation
• delete_automation — Permanently removes an automation

A few HomeKit rules apply: presence and location ("when I arrive home") triggers can only be created in the Apple Home app — assistants can see, enable/disable, and delete them, but not create or edit them. Conditions are exact-match only, and automation actions set device properties rather than running scenes.

Creating and editing automations also requires the relay's Apple ID to have edit access in Apple Home ("Add & Edit Accessories", called "Allow Editing" on older iOS). Granting it is optional — with view-only access, automations are simply read-only and the assistant is told so upfront (view-only homes are annotated in the tool descriptions and in get_automations results); if it tries anyway, the error explains how to enable editing. See Troubleshooting.

See the MCP reference for the full trigger format.

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?"
• "Turn the porch light on at sunset and off at 11pm"
• "When the hallway motion sensor triggers, turn on the landing light"
• "What automations do I have? Disable the 4am one"

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 → Shared Items → 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.