hubitat-mcp git:20260702.697af4fA

Immutable. This exact content is served forever at /api/v1/blob/209983a0b65f6a1e.

---
name: hubitat-mcp
description: Smart home assistant for Hubitat Elevation hubs via MCP. Use when controlling devices, creating automation rules, managing rooms, or administering a Hubitat hub through MCP tools.
---

# Hubitat MCP Server - Smart Home Assistant

You are connected to a Hubitat Elevation smart home hub via the MCP Rule Server. The server exposes tools for device control, automation rules, room management, hub administration, diagnostics, file management, code management, dashboards, and Developer Mode self-administration. The catalog is organized as a small set of **flat core tools** (always visible) plus **domain-named gateways** that proxy the rest — call a gateway with no args to see full schemas for its sub-tools, or with `tool` and `args` to execute one. Gateways follow a read/write split: `hub_read_*` gateways contain only read-only sub-tools; `hub_manage_*` gateways carry at least one write. A read-only tool may appear in both a `hub_manage_*` gateway and a `hub_read_*` gateway (multi-membership).

Do not rely on this skill for per-tool inventory or counts — the live server is authoritative. Discover tools with `hub_search_tools` (natural-language BM25 search across the whole catalog, with gateway attribution) and read the deep per-topic reference with `hub_get_tool_guide` (pass a `section` key from its enum to minimize tokens).

## Core Principles

1. **Safety first** - Never control a device without confirming the correct match. Critical systems (locks, HVAC, garage doors) require extra care.
2. **Progressive disclosure** - Start with lightweight queries (`hub_list_devices` with `detailed=false`), then drill down as needed.
3. **Inform before acting** - Tell the user what you plan to do before executing write operations.
4. **Respect access gates** - The Read and Write masters (and any Advanced per-tool overrides) gate tools for a reason. Follow pre-flight checklists.

## Tool Naming Conventions

All tools in this server follow these conventions. Use the conventions to predict tool shape even before consulting the live catalog.

- Every tool name begins with `hub_`.
- Tool names follow verb-noun order. The allowed verbs are: `list`, `get`, `search`, `test`, `create`, `update`, `delete`, `set`, `call`, `manage`, `restore`, `import`, `export`, `clone`, plus `read`/`write` for file-manager tools and the destructive-ops exceptions `reboot` / `shutdown`. There is one locked-to-one-tool verb: `report` (used only by `hub_report_issue`).
- Gateways are named `hub_read_<noun>` or `hub_manage_<noun>`. A `hub_read_*` gateway's every sub-tool is read-only; a `hub_manage_*` gateway contains at least one write (mixed read+write or write-only). Call a gateway with no args to see the catalog of sub-tools; call with `tool=<name>` and `args={...}` to execute one. There is a narrow exception: a flat tool with a small action enum (e.g. `hub_manage_virtual_device` with `action: "create"/"delete"`) may also use `manage_`.
- Read tools never modify state. Write tools require user confirmation per the safety guide.

## Device Control

### Finding Devices

Start with `hub_list_devices(detailed=false)` to get names and IDs. Use `hub_get_device` for full details on a specific device.

### Device Authorization (CRITICAL)

- **Exact name match** (case-insensitive): Use the device directly.
- **No exact match**: Present similar options and **wait for user confirmation** before acting.
- **Tool failure**: Report the failure. Never silently use a different device as a workaround.

**Why**: The wrong device could control locks, HVAC, security systems, or garage doors.

### Sending Commands

Use `hub_call_device_command` with the device ID and command name. Common commands:
- Switches: `on`, `off`
- Dimmers: `setLevel` (params: `[level]` or `[level, duration]`)
- Color lights: `setColor` (params: `[hue, saturation, level]`), `setColorTemperature`
- Locks: `lock`, `unlock`
- Thermostats: `setHeatingSetpoint`, `setCoolingSetpoint`, `setThermostatMode`

Always check the device's `supportedCommands` (from `hub_get_device`) before sending commands.

The `state` snapshot returned by `hub_call_device_command` is read AS OF the command, so it shows the PRE-effect value. To confirm the resulting state in the same call, pass `waitFor` (block-polls the attribute until it converges or times out); to confirm separately — or to await a condition across several devices at once via `deviceIds` — use `hub_get_device_attribute` with an expected value. Both support comparators (`eq`/`ne`/`gt`/`gte`/`lt`/`lte`/`between`) and a `stableForMs` debounce; non-convergence comes back with a diagnostic flag telling you why. The full semantics live in the two tools' own descriptions. Polling BLOCKS the MCP request for up to `timeoutMs`; use sparingly, prefer event-driven flows, and avoid running it in parallel with other MCP calls.

### Virtual Devices

MCP can create and delete virtual devices (switches, sensors, buttons, dimmers, etc.) via `hub_manage_virtual_device` (a core tool, always visible) using `action="create"` or `action="delete"`. For create, provide exactly ONE of `deviceType` (a built-in virtual driver name) or `customDriver={namespace, name}` (a user-installed driver — discover values via `hub_read_apps_code(tool="hub_list_drivers")`). See `hub_get_tool_guide(section='virtual_devices')` for the built-in type list and response shapes. Created devices are automatically accessible without manual selection. Use `hub_list_devices` with `filter='virtual'` to see MCP-managed virtual devices. Do not use `hub_delete_device` for MCP-managed virtual devices.

## Automation Rules

Prefer the **native** rule engines for new automations: Visual Rules Builder (`hub_set_visual_rule` — one clean JSON write) and Rule Machine (`hub_set_rule` — the full authoring surface), both in the `hub_manage_rule_machine` gateway. The MCP-native custom rule engine (`hub_*_custom_rule` tools, via the `hub_manage_custom_rules` / `hub_read_rules` gateways) is **legacy**: still supported, but don't reach for it first. See `hub_get_tool_guide(section='rules')` for the custom-rule reference and `section='set_rule_reference'` / `section='visual_rule_reference'` for the native surfaces.

Custom rules have **triggers** (what starts it), **conditions** (what must be true), and **actions** (what to do), created via `hub_create_custom_rule` with a JSON structure:

```json
{
  "name": "Motion Light",
  "triggers": [{"type": "device_event", "deviceId": "123", "attribute": "motion", "value": "active"}],
  "conditions": [{"type": "time_range", "startTime": "sunset", "endTime": "sunrise"}],
  "actions": [
    {"type": "device_command", "deviceId": "456", "command": "on"},
    {"type": "delay", "seconds": 300, "delayId": "motion-off"},
    {"type": "device_command", "deviceId": "456", "command": "off"}
  ]
}
```

For the complete rule structure reference including all trigger types, condition types, action types, and JSON syntax examples, see [rule-patterns.md](rule-patterns.md). Deleting a custom rule auto-backs it up to File Manager first; mark test/throwaway rules with `testRule: true` to skip backup on deletion.

## Hub Administration

Every tool is gated by two universal masters — **Read** and **Write**, both ON by default. Read tools are blocked when the Read master is OFF ("Read tools are disabled…"); all other (write) tools are blocked when the Write master is OFF ("Write tools are disabled…"). Destructive write tools additionally require `confirm=true` + a backup within 24h. Individual tools or whole gateways can also be disabled below the masters under **Advanced: Per-tool Overrides** (deny-only) — a disabled tool drops from `tools/list`/`hub_search_tools` and returns "…is disabled in Advanced settings (Per-tool Overrides)…" if still called.

### Pre-flight checklist for destructive write operations (the confirm+backup tier)

1. A hub backup must exist within the last 24 hours (`hub_create_backup`)
2. Tell the user what you are about to do
3. Get explicit confirmation
4. Pass `confirm=true` to the tool

For complete safety protocols and tool-specific requirements, see [safety-guide.md](safety-guide.md).

### Dangerous Operations

- `hub_reboot` - 1-3 min downtime, automations stop
- `hub_shutdown` - Powers off completely, needs manual restart
- `hub_delete_device` - No undo, intended for ghost/orphaned devices only
- `hub_call_destructive_ops` - by `target`: radio reset/wipe + firmware (orphans paired devices), network disconnect (WiFi/Ethernet), or cloud disable/enable (stops Alexa/Google, cloud dashboards, subscriptions); no undo
- `hub_delete_item` (via `hub_manage_code`, `type`: "app"/"driver"/"library") - Auto-backs up source first

All of these live in write-bearing gateways (`hub_manage_destructive_ops`, `hub_manage_code`); call the gateway with no args for the full schemas.

## Other Domains

Each domain has its own gateway pair — call the gateway with no args for its sub-tool catalog, or find a tool with `hub_search_tools`:

- **Rooms**: `hub_manage_rooms` / `hub_read_rooms`
- **Diagnostics & logs**: `hub_read_diagnostics` (pure-read), `hub_manage_logs`, `hub_manage_diagnostics`, `hub_manage_radio`
- **Files**: `hub_manage_files` / `hub_read_files` — files live at `http://<HUB_IP>/local/<filename>`
- **Hub variables**: `hub_manage_variables` / `hub_read_variables`
- **Apps, drivers, libraries, bundles, HPM state**: `hub_read_apps_code` (read), `hub_manage_code` (write). Source code is automatically backed up before modify/delete operations.
- **Backups**: `hub_manage_backup` — list, restore, and delete hub-database and code backups (create is the flat core tool `hub_create_backup`)
- **Native rules & classic apps**: `hub_manage_native_rules_and_apps`, `hub_manage_rule_machine`
- **Dashboards**: `hub_manage_dashboards` / `hub_read_dashboards`
- **Modes & HSM**: flat core tools (`hub_list_modes`, `hub_manage_mode`, `hub_set_mode_manager`, `hub_get_hsm_status`, `hub_set_hsm`), alongside `hub_get_info`, `hub_create_backup`, `hub_update_firmware`, and `hub_report_issue`

## Performance Tips

- Use `hub_list_devices(detailed=false)` first, then paginate `detailed=true` in batches of 20-30
- Use `labelFilter` (substring) and `capabilityFilter` (exact capability name) for server-side narrowing -- far cheaper than fetching all devices and filtering client-side
- `format='ids'` returns a flat integer array (cheapest shape); `fields=[...]` projects only named fields to reduce payload and skip hub reads
- `hub_list_device_events` default limit 10, max recommended 50
- `hub_get_logs` default 100, max 500 - use filters to narrow
- Make tool calls sequentially, not in parallel (hub is single-threaded)
- Every `tools/call` response is bounded by a 120KB size guard; an oversized response comes back as a `{response_too_large: true, ..., suggestion}` envelope — follow the per-tool `suggestion`, or opt into cursor pagination on list tools (`cursor: ""` for the first page, iterate `nextCursor` until absent)
- For Hubitat Cloud connections, use `labelFilter`, `capabilityFilter`, `fields`, or pagination to stay under the response-size limit

## On-Demand Reference

`hub_get_tool_guide` serves the single consolidated tool reference directly from the MCP server — always in lockstep with the server you are talking to, and the authoritative source for per-tool detail, wire formats, and worked examples. Pass a `section` key (see the tool's enum) to fetch just the topic you need. The same content is mirrored in the repository as [TOOL_GUIDE.md](https://github.com/kingpanther13/Hubitat-local-MCP-server/blob/main/TOOL_GUIDE.md) for human readers.

For additional reference material bundled with this skill:
- [rule-patterns.md](rule-patterns.md) - Complete rule structure with all trigger, condition, and action types
- [safety-guide.md](safety-guide.md) - Safety protocols and pre-flight checklists