Skip to content

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 accessories
  • set_state — Control accessories (turn on/off, set brightness, etc.)
  • get_history / query_history — Read what your home has recorded, when Analytics is on
  • 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
  • get_hc_automations / create_hc_automation / update_hc_automation / delete_hc_automation — Build and manage Homecast automations, which can do things HomeKit cannot
  • create_virtual_accessory / update_virtual_accessory / delete_virtual_accessory — Create and edit values your home remembers, for automations that need memory

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".

All of them connect to the same endpoint:

https://api.homecast.cloud/mcp

Signing in uses OAuth: the first time an assistant connects, your browser opens a Homecast page where you sign in and approve it.

Setup for Claude (claude.ai, Desktop and mobile) ​

  1. In Claude, open Customize → Connectors
  2. Click + Add → Add custom connector
  3. Name it Homecast and enter https://api.homecast.cloud/mcp as the URL
  4. Click Add, then Connect to sign in to Homecast

If Claude asks how to register the OAuth client, choose Register automatically.

A connector added on claude.ai is available in Claude Desktop and the Claude mobile apps too. On Team and Enterprise plans, an organization owner adds the connector under Organization settings → Connectors, and members then click Connect on it. Claude's menus change from time to time — see Anthropic's custom connector guide for the current steps and plan limits.

Setup for Claude Code ​

bash
claude mcp add --transport http homecast https://api.homecast.cloud/mcp

Then run /mcp inside Claude Code and choose homecast to sign in. To share the server with a project, add it to .mcp.json:

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

Setup for ChatGPT ​

ChatGPT connects to MCP servers in developer mode, which OpenAI currently offers on the web for paid plans; which plans can use write actions has changed more than once, so check OpenAI's developer mode guide for yours.

  1. Turn on Developer mode in ChatGPT's settings
  2. Create a new app or connector, and enter https://api.homecast.cloud/mcp as the MCP server URL with OAuth authentication
  3. Sign in to Homecast when prompted
  4. In a chat, choose Developer mode from the + menu and select Homecast

ChatGPT may ask you to confirm before it runs a Homecast tool, especially one that changes something in your home.

Approving access ​

Whichever assistant you use, Homecast shows the same approval page:

  1. Sign in to your Homecast account
  2. Choose which homes the assistant can reach
  3. For each home, choose View only or Full control
  4. Click Authorize

OAuth consent screen

Every home starts ticked with Full control — untick homes the assistant doesn't need, and switch to View only where it should only read. The assistant renews its sign-in automatically; if it goes unused for about a month, it will ask you to sign in again.

Setup with an access token ​

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 → Create Token
  3. Create a token with the desired home permissions
  4. Configure your MCP client with the token as a Bearer header. In Claude Code:
bash
claude mcp add --transport http homecast https://api.homecast.cloud/mcp \
  --header "Authorization: Bearer hc_your_token_here"

Or in a client's JSON configuration:

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

Available tools ​

get_state ​

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

ParameterTypeRequiredDescription
filter_by_homestringNoOnly show accessories in this home
filter_by_roomstringNoOnly show accessories in this room
filter_by_typestringNoOnly show this type (e.g., light, climate, lock, temperature)
filter_by_namestringNoOnly show accessories matching this name

set_state ​

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

ParameterTypeRequiredDescription
updatesarrayYesList of accessory updates
updates[].homestringYesHome name
updates[].roomstringYesRoom name
updates[].accessorystringYesAccessory name
updates[].onbooleanNoPower state
updates[].brightnessintegerNoBrightness 0–100
updates[].hueintegerNoColor hue 0–360
updates[].saturationintegerNoColor saturation 0–100
updates[].color_tempintegerNoColor temperature (mireds)
updates[].hvac_modestringNoHVAC mode: auto, heat, cool (turn off with active: false)
updates[].target_tempfloatNoThermostat target temperature
updates[].heat_targetfloatNoHeating target temperature
updates[].cool_targetfloatNoCooling target temperature
updates[].lock_targetintegerNo1 = lock, 0 = unlock
updates[].speedintegerNoFan speed 0–100
updates[].targetintegerNoPosition 0–100 (blinds, garage)

run_scene ​

Execute a HomeKit scene by name.

ParameterTypeRequiredDescription
homestringYesHome name
namestringYesScene name

History tools ​

When Analytics is on for a home, the assistant can answer questions about the past:

  • get_history — One accessory's recorded history: "what was the temperature in the bedroom last night?"
  • query_history — Many accessories and characteristics at once, over any date range, for spotting patterns: "which room is coldest in the mornings?"

If Analytics is off, both tools say so rather than returning an error. See the MCP reference for parameters.

Automation tools ​

Homecast can build automations in two places, and an assistant picks between them:

HomeKit automationsHomecast automations
Where they runYour Apple home hubThe Homecast relay Mac
Keep working with the Mac offYesNo
Show up in the Apple Home appYesNo — they live in Homecast
"When humidity goes above 65%"Not possible — exact matches onlyYes
Remember something between runsNoYes, using virtual accessories
Delays, notifications, running scenesNo — accessory properties onlyYes

Assistants default to Homecast automations, because they can express far more, and switch to HomeKit when the automation needs to survive the Mac being off or the user wants it visible in Apple Home.

If you have ever been told a request was impossible — a threshold, or "don't do it again if it's already running" — that was HomeKit's limit, not Homecast's. Those work now.

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, an accessory changing state, or a repeating interval), optional conditions, and accessory 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 accessory 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.

Homecast automations ​

The visual-editor automations — the assistant builds them the same way you would, and you can open and edit any of them afterwards:

  • get_hc_automations — Lists Homecast automations per home, with their triggers, conditions and actions
  • create_hc_automation — Creates one from triggers (including numeric thresholds), optional AND/OR/NOT conditions, and actions that can set accessories, run scenes, wait, notify, or change a virtual accessory
  • update_hc_automation — Renames, enables/disables, or modifies one
  • delete_hc_automation — Permanently removes one

None of this needs edit access in Apple Home — these automations are Homecast's, not HomeKit's. They do need the relay Mac to be awake and running Homecast, since that is where they execute.

For automations that need to remember something — whether a cycle is already running, what mode the house is in, a value to restore later — the assistant creates a virtual accessory with create_virtual_accessory and reads it in a condition. update_virtual_accessory renames one or changes its settings later — adding a choice to a mode, widening a number's range — without disturbing the value it is currently holding. Ask for "run the dehumidifier when it gets damp, but not if I've turned the aircon on myself" and that is what it will build. There is a worked example in the MCP reference.

Assistants cannot yet build automations that use code nodes, HTTP requests or branching — those are visual-editor features. An automation using them is listed as editable_via_mcp: false, and the assistant will offer to rename, pause or delete it rather than silently rewriting it and dropping the parts it cannot express.

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's in the bedroom?"
  • "How many times did the front door open yesterday?"
  • "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 home's state, figures out the right API calls, and executes them.

Security ​

  • Home-scoped permissions — Each assistant only sees the homes you ticked when approving it, with View only or Full control for each
  • Review authorized apps — Settings → Sharing → Authorized Apps lists every assistant you've approved. Change its homes and permissions, or revoke it

Authorized apps

  • Separate tokens per assistant — If you use access tokens, create a dedicated one for each integration so you can revoke them individually
  • Revoke access — Revoking an app stops it renewing its sign-in at once; delete a token under Settings → API Access

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