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

For broad "what's going on / what's in this house" questions, start with hub_list_devices(format='context') — one token-cheap plain-text snapshot (mode + one Label (id, room) - capabilities; attr=value line per device), filterable with roomFilter / onlyOn / changedSince / attributeNames. For targeted lookups, hub_list_devices(detailed=false) gets 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:

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

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 for human readers.

For additional reference material bundled with this skill:

• rule-patterns.md - Complete rule structure with all trigger, condition, and action types
• safety-guide.md - Safety protocols and pre-flight checklists