HomeKit Smart Home Control

HomeClaw exposes Apple HomeKit accessories via MCP tools. Use the homekit_* tools as the interface for all HomeKit operations.

MCP Tools

The plugin registers 8 MCP tools.

homekit_device_map

Returns a complete LLM-optimized device map organized by home/zone/room hierarchy. Each device includes:

Use this tool first when you need to understand the device landscape before controlling devices. It resolves name collisions and identifies switches that actually control lights.

Semantic Type Reference

homekit_accessories

The main workhorse tool. Supports 4 actions via the action parameter:

homekit_scenes

homekit_events

homekit_automations

Each scene, and each entry in an automation's action_sets, carries last_execution_date (ISO-8601 UTC, or null). HomeKit leaves it null for most runs, including automations a home hub runs, so null means "none recorded", not "never ran". Use events for what actually happened.

Create parameters:

Inline actions vs scenes: Use actions for simple button-to-device mappings (creates a scene named after the automation). Use scene_id to trigger an existing shared scene. Note: Apple's Home app uses a private API for hidden automation-only action sets; inline actions created via HomeClaw will appear as visible scenes.

homekit_config

Common Workflows

Turn on a light

1. Search for the light: homekit_accessories with action: "search", query: "kitchen"
2. Identify the accessory UUID from the results
3. Turn it on: homekit_accessories with action: "control", accessory_id: "<uuid>", characteristic: "power", value: "true"

Set brightness

1. Find the light UUID (via search or list)
2. Set brightness: homekit_accessories with action: "control", accessory_id: "<uuid>", characteristic: "brightness", value: "50"

Lock all doors

1. Find all locks: homekit_accessories with action: "search", category: "lock"
2. For each lock: homekit_accessories with action: "control", accessory_id: "<uuid>", characteristic: "lock_target_state", value: "locked"

Check temperature

1. Find thermostats: homekit_accessories with action: "search", category: "thermostat"
2. Get details: homekit_accessories with action: "get", accessory_id: "<uuid>"
3. Read the current_temperature characteristic from the response

Set thermostat

1. Find the thermostat UUID (via search)
2. Set temperature: homekit_accessories with action: "control", accessory_id: "<uuid>", characteristic: "target_temperature", value: "72"
3. Set mode: homekit_accessories with action: "control", accessory_id: "<uuid>", characteristic: "target_heating_cooling", value: "auto"

Run a scene

1. List scenes: homekit_scenes with action: "list"
2. Trigger: homekit_scenes with action: "trigger", scene_id: "Movie Time"

Inspect what a scene does

1. Get scene detail: homekit_scenes with action: "get", scene_id: "Good night"
2. Response includes all actions: accessory name, room, characteristic, and target value

List accessories by room

1. Filter by room: homekit_accessories with action: "list", room: "Living Room"

Switch active home

1. Configure: homekit_config with action: "set", default_home_id: "My Home"

Program a button (inline actions)

Creates a scene named after the automation and links it to the button press. Always use UUIDs for target accessories to avoid name collisions (many accessories share names like "Overhead" or "Blinds" across rooms).

1. Find the button: homekit_accessories with action: "search", query: "Office Button"
2. Find target devices and note their UUIDs: homekit_accessories with action: "list", room: "Sarah's Bedroom"
3. Check button services: homekit_accessories with action: "get", accessory_id: "<button-uuid>" to see how many buttons and press types (input_event max: 0=single only, 2=single+double+long)
4. Create automation: homekit_automations with action: "create", name: "Room Open", accessory_id: "<button-uuid>", actions: [{accessory: "<light-uuid>", property: "power", value: "true"}, {accessory: "<blind-uuid>", property: "target_position", value: "100"}], press_type: 0, service_index: 1

Program a button (with a named scene)

Use when the automation should trigger an existing scene:

1. Find the button and identify the scene
2. Create automation: homekit_automations with action: "create", name: "Button → Movie Time", accessory_id: "<button-uuid>", scene_id: "Movie Time", press_type: 0

Edit a scene's actions in place (CLI)

Repoints an existing scene at different accessories/values without changing its UUID, so automations that trigger it stay wired. Only update-scene / import-scene (CLI) can do this — there is no MCP tool for it. Common use: point a slow "set each shade" scene at a single vendor "scene switch" so one press moves everything at once.

1. Inspect current actions: homeclaw-cli get-scene "Main Blinds - Open" --json
2. Write the new definition. Actions are {"accessory", "property", "value"}; characteristic is accepted as an alias for property, so get-scene output round-trips. Reference accessories by UUID when names collide.

   { "name": "Main Blinds - Open",
     "actions": [ { "accessory": "Open Main Blinds", "property": "power", "value": "1" } ] }

3. Dry-run, then apply. Pipe via stdin (-) to avoid the sandbox file limit below:

   cat scene.json | homeclaw-cli update-scene - --dry-run    # check resolved_actions
   cat scene.json | homeclaw-cli update-scene -

   --dry-run reports resolved_actions; if it's below your action count, an accessory/property didn't resolve — read the warnings.

Sandbox file access. homeclaw-cli is sandboxed to the app group, so it can only open files under ~/Library/Group Containers/group.com.shahine.homeclaw/ (or system paths). Files in /tmp, ~/Desktop, or agent temp dirs fail with "couldn't be opened because you don't have permission to view it" — this is not fixed by granting Full Disk Access. Pipe JSON via stdin (-), or place the file in the group container.

Detach a hidden scene from a button (CLI)

Buttons sometimes carry hidden, trigger-owned scenes (e.g. an auto-generated close-all fired alongside an open) that get-scene can see but update-scene/delete-scene cannot edit (they only search visible scenes). Detach them from the automation instead:

1. Find the automation: homeclaw-cli automations list --json
2. Detach the scene (--add-scene/--remove-scene repeatable, --dry-run supported, trigger UUID preserved):

   homeclaw-cli automations rewire "<automation id>" --remove-scene "<scene name or uuid>" --dry-run
   homeclaw-cli automations rewire "<automation id>" --remove-scene "<scene name or uuid>"

Button modes and service_index

Programmable switches (Aqara, Hue, etc.) may operate in different modes:

• Fast mode: Multiple buttons (e.g., Button 1 and Button 2), each single-press only. Fires instantly with no delay. Identified by input_event metadata max: 0 on each service.
• Multi-event mode: One button with single, double, and long press. Adds ~300ms delay to detect press type. Identified by input_event metadata max: 2.

Use --service-index (CLI) or service_index (MCP) to target a specific button in fast mode. The mode itself is configured in the manufacturer's app (e.g., Aqara Home), not via HomeKit.

Name each gang of a multi-gang accessory, and set Display As

A dual relay (e.g. Aqara Dual Relay T2) is one accessory with two switch services; every gang shares the accessory UUID and serial. Separating its tiles in the Home app only changes layout. Plain rename names the accessory and its primary tile only — name the other gang by service:

homeclaw-cli get "Downlight 1" --json          # services[] lists each gang's id, name, index, display_as
homeclaw-cli rename "Downlight 1" "Downlight 2" --service-name "Switch 2"   # or --service-index 2 / --service-id <uuid>
homeclaw-cli rename <service-uuid> "Downlight 2"                            # a service UUID also works as the target
homeclaw-cli set-display-as "Downlight 1" light --service-name "Downlight 2" --dry-run

Group accessories into one tile

A Home app group ("Group with Other Accessories") is one tile and one Siri target for several accessories, e.g. all ceiling lights in a room. Members are services, so one gang of a dual relay can join on its own via its service UUID. Separating a multi-gang accessory's tiles is different: that's layout only, not a group.

homeclaw-cli groups                                                    # existing groups and members
homeclaw-cli groups create "Lounge Ceiling" "Downlight 1" <switch-2-service-uuid> --dry-run
homeclaw-cli groups add "Lounge Ceiling" "Stairs LED"
homeclaw-cli groups remove "Lounge Ceiling" "Stairs LED"
homeclaw-cli groups rename "Lounge Ceiling" "Lounge Lights"
homeclaw-cli groups delete "Lounge Lights"                             # accessories are untouched

Members must be lights, switches, outlets, fans, or window coverings, and one kind per group (lights with lights), as in the Home app; set a relay's Display As to light first so it counts as a light, or pass --allow-mixed. MCP: homekit_manage actions list_groups, create_group, add_to_group, remove_from_group, rename_group, delete_group with group, members, allow_mixed.

MCP: homekit_manage with action: "rename" or action: "set_display_as" plus service_name / service_index / service_id. This writes the home's service name, so it works even when the gang's HAP name characteristic is read-only. Display As (light, fan, or the service's own switch / outlet; default restores it) applies only to switch and outlet services — a gang bridged over Matter as a light has no Display As, in the Home app or here.

Error Handling

Configuration

Config file: ~/.config/homeclaw/config.json

Use homekit_config to view and modify settings. When temperature_unit changes, the characteristic cache is automatically invalidated and refreshed.

Accessory Categories

Categories are mapped from Apple's HMAccessoryCategoryType constants. Homebridge devices that don't map to a known category will show the raw UUID string.

Characteristics by Category

Lightbulb

Thermostat

Note: Temperature values are returned as formatted strings with the user's preferred unit (e.g., "71°F" or "22°C"). This applies to all current_temperature readings across all accessory types (thermostats, sensors, leak detectors, etc.).

Lock

Door / Garage Door

Fan

Window Covering

Sensor (common)

Enum Value Mappings

Heating/Cooling State

Lock State

Door State

JSON Response Structure

list / search Response

Each accessory includes name, id, category, room, reachability, and a summary of current state values.

get Response

Full detail includes all services and their characteristics, each with name, current value, and writable flag.

status Response