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 accessoriesset_state— Control accessories (turn on/off, set brightness, etc.)get_history/query_history— Read what your home has recorded, when Analytics is onrun_scene/create_scene/update_scene/delete_scene— Execute and manage HomeKit scenesget_automations— List your HomeKit automationscreate_automation/update_automation/delete_automation— Build and manage HomeKit automationsget_hc_automations/create_hc_automation/update_hc_automation/delete_hc_automation— Build and manage Homecast automations, which can do things HomeKit cannotcreate_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/mcpSigning 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)
- In Claude, open Customize → Connectors
- Click + Add → Add custom connector
- Name it Homecast and enter
https://api.homecast.cloud/mcpas the URL - 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
claude mcp add --transport http homecast https://api.homecast.cloud/mcpThen run /mcp inside Claude Code and choose homecast to sign in. To share the server with a project, add it to .mcp.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.
- Turn on Developer mode in ChatGPT's settings
- Create a new app or connector, and enter
https://api.homecast.cloud/mcpas the MCP server URL with OAuth authentication - Sign in to Homecast when prompted
- 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:
- Sign in to your Homecast account
- Choose which homes the assistant can reach
- For each home, choose View only or Full control
- Click Authorize

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:
- Enable Developer Mode in Settings → Account at homecast.cloud
- Go to Settings → API Access → Create Token
- Create a token with the desired home permissions
- Configure your MCP client with the token as a Bearer header. In Claude Code:
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:
{
"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.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter_by_home | string | No | Only show accessories in this home |
filter_by_room | string | No | Only show accessories in this room |
filter_by_type | string | No | Only show this type (e.g., light, climate, lock, temperature) |
filter_by_name | string | No | Only 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
updates | array | Yes | List of accessory 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: auto, heat, cool (turn off with active: false) |
updates[].target_temp | float | No | Thermostat target temperature |
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 |
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 automations | Homecast automations | |
|---|---|---|
| Where they run | Your Apple home hub | The Homecast relay Mac |
| Keep working with the Mac off | Yes | No |
| Show up in the Apple Home app | Yes | No — they live in Homecast |
| "When humidity goes above 65%" | Not possible — exact matches only | Yes |
| Remember something between runs | No | Yes, using virtual accessories |
| Delays, notifications, running scenes | No — accessory properties only | Yes |
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 editablecreate_automation— Creates an automation from a trigger (time of day, sunrise/sunset, an accessory changing state, or a repeating interval), optional conditions, and accessory actionsupdate_automation— Renames, enables/disables, or modifies an automationdelete_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 actionscreate_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 accessoryupdate_hc_automation— Renames, enables/disables, or modifies onedelete_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

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