Tool reference

71 tools, grouped by security scope. This page is generated from the plugin’s own tool registry (mcp_server/registry.py), where each tool declares its scope alongside its schema, so it can never drift from the code. Regenerate with python3 scripts/generate_tool_doc.py --write. A read-only token can call only the Read tools, a read-write token the Read + Write tools, and admin is required for the Admin tools. For a friendlier overview organised by function (devices, heating, energy, …) see What it does.

Tools that other plugins contribute (see Letting your plugin add tools) are not in this table: they come and go with the plugins that ship them, and each is listed under its own prefix on top of the 71 below.

A note on variable values. The Read tools that return variables (get_variable_by_id, list_variables, home_status and the like) return each variable’s value in full, so any token with the read scope can see them. If you keep a secret in an Indigo variable — an API token, a password — bear in mind that a read-only Claude Bridge token can read it, the same way any Indigo script or control page can. Keep genuine secrets in IndigoSecrets.py rather than in a variable, and don’t hand a read token to anyone you wouldn’t trust with those values. (Claude Bridge no longer writes a variable’s full value into the event log either — long values are shortened in the log line, though they’re still returned to the caller as normal.)

Read tools (30)

Pure queries — no state change. Require the read scope.

Tool	Description
`audit`	Run one health check, chosen by check. home: the overview — devices in error, low battery, stale devices, empty variables, disabled triggers and schedules, automation counts. errors: devices in an error or fault state. low_battery: battery below threshold % (default 20), lowest first. stale: enabled devices unchanged for more than days (default 7). variables: variables no script references, and empty/None/’null’ values. conflicts: duplicate device or trigger names, devices sharing a hardware address, scripts naming deleted ids, several scripts writing one variable. orphaned_scripts: scripts referencing device or variable ids that no longer exist. orphaned_plugin_data: prefs folders, .indiPref files and LaunchAgents left by uninstalled plugins — read a prefs file before deleting it, credentials have been found in them. deprecated: Indigo’s deprecated objects (include_warnings adds warning-level ones). api_coverage: the live indigo.* namespaces against the frozen baseline, after an Indigo upgrade. large_files: files of at least min_mb MB (default 10) under path (default the Indigo install folder), largest first, up to max_results (default 50).
`change_log`	The permanent record of every change made through Claude Bridge: each call that needs the write or admin scope, whether it worked, failed or was refused. Each entry gives the time, the access key’s NAME (never the key), the tool, its arguments with every known secret blanked (including the full Python or script it ran), the outcome (ok, failed, refused, or running for a background job, whose end has its own ‘job finished’ entry) and how long it took. Newest first. Filters match exactly, ignoring case. Argument text is cut to 200 characters unless full=true. Kept in monthly files in the plugin’s Preferences folder, which nothing deletes.
`check_plugin_updates`	Sweep every installed plugin and report which have a compatible update available. One call instead of one get_plugin_status per plugin.
`control_pages`	Without page_id, list every control page (id, name, folder and so on). With page_id, one page’s properties AND its full layout: every element with its type, position, size, caption, and the device/variable/action group it points at. Elements whose target no longer exists are flagged, so this finds controls left behind by a deleted device.
`device_history`	Read recent SQL Logger history for one device, from the SQLite SQL Logger database (a PostgreSQL SQL Logger is not read). Returns timestamp + non-null state columns. Column names are stored LOWERCASE (batterysoc, not batterySoc). An unknown name is an error listing the valid columns. Rows are sparse — only changed values are written, so forward-fill before deriving trends. `limit` caps rows from the NEWEST end, so on a chatty device it can cut the window far shorter than `hours` — check `truncated` and the `ts_oldest`/`ts_newest` span before concluding anything about earlier events.
`energy_history`	Per-day kWh totals from SigenEnergyManager’s own daily record: PV generated, grid imported, grid exported, home consumption, max/min SOC and self-sufficiency, over the last `days` complete days (default 14, max 90), with today’s running totals as today_so_far. compare=true instead sets those days against an equally long earlier period ending compare_offset_days before them (default: the period just before) and returns kWh deltas and percentage changes.
`find_automation_references`	Reverse lookup: which triggers/schedules/action groups reference a device, variable, or action group — role-tagged (watches / condition_reads / acts_on / sets / executes) and following action-group execution chains transitively. Cross-checked against the server’s own dependency graph, AND against both Python script folders on disk (entity_type ‘script’, role ‘script_reference’, with line numbers) which getDependencies does not cover. Also text-scans EMBEDDED scripts — scripted conditions, trigger/schedule action scripts and action-group scripts — by numeric ID and by quoted name, and those hits carry confidence ‘heuristic’. Plugins that hard-code an ID in their own source remain uncovered. Richer than get_dependencies for automation debugging and safe-delete checks.
`get_automation`	Full definition of one trigger, schedule or action group: event settings (triggers), decoded timing (schedules: time/date type, sun offsets, repeat interval), conditions, and the ACTION STEPS — device commands, variable sets, embedded and linked scripts, plugin actions — that the IOM does not expose. Read from Indigo’s database file, so very recent edits may lag by a few minutes.
`get_dependencies`	Indigo’s own getDependencies() for one object: which devices, variables, triggers, schedules, action groups and control pages the server records as depending on it. Useful before deleting. For a device or variable, find_automation_references is richer: it tags each reference with its role, follows action-group chains and scans scripts, none of which the server’s own graph covers.
`get_device_by_id`	Get a specific device by ID: its properties, states, props and capabilities, plus `group` (the devices Indigo groups it with, root first) when it is part of one.
`get_device_by_name`	Find a device by name and return its full state in one round trip. Tries exact match, then case-insensitive, then partial match. Returns all device states, properties, and current values, like get_device_by_id.
`get_plugin_status`	One installed plugin by bundle id: enabled, running (enabled only says it SHOULD run — a plugin that died in startup() is still enabled, while running answers ‘did the restart work’), display name, version and bundle path. An id that is not installed is an error, not a disabled plugin. include_prefs=true adds the plugin’s saved settings (its Configure dialog values, as last saved to disk) with passwords, keys and tokens hidden. Never cached.
`get_variable_by_id`	Get a specific variable by ID
`home_status`	The state of the house. section=’summary’ (default): every device grouped by type, key variable values, energy status, active alerts (errors, low battery) and automation counts. ‘energy’: a live SigenEnergyManager snapshot — battery SOC, solar, grid import/export, tariff. ‘heating’: every thermostat/TRV with setpoints, temperatures and zone modes. ‘security’: open doors and windows, active motion, leak/smoke/CO alerts. ‘report’: a markdown prose report to show the user as it stands. report_sections picks sections (energy, heating, security, devices, alerts, automation), default all.
`investigate_event`	Answer ‘what caused this device change?’ — finds the change in the event log, collects trigger/schedule/action-group activity in a window around it, and ranks candidates by temporal proximity plus structural evidence (does the automation actually act on the device, directly or through action-group chains?). Reports likelihood with evidence, never certainty.
`list_action_groups`	List action groups. Sorted by name, a page at a time: the reply says total, offset, count and next_offset, and offset=next_offset gets the next page until it is null.
`list_devices`	List devices, a page at a time, sorted by name. With no filter the page is 50 full device rows — prefer a filter or `fields`. device_type narrows to one type (aliases accepted), plugin_id to one plugin’s devices, folder to one device folder (id or name), and state_filter to devices whose states match, e.g. {“onState”: true} or {“heatIsOn”: true}. fields returns just id, name and the properties or states named, e.g. [“address”, “batteryLevel”]. Every reply says total, offset, count and next_offset: call again with offset=next_offset for the next page, until next_offset is null. limit sets the page size (default 50 with no filter or 200 with one, and at most 1000).
`list_plugins`	List all Indigo plugins
`list_python_scripts`	List the Python scripts (.py files) in the Indigo script folders with name, size, last-modified date and full path. With backups_for, list the automatic backups kept for that one script instead, newest first.
`list_schedules`	List Indigo schedules with their ID, name, enabled state, and next scheduled execution time. Sorted by name, a page at a time: the reply says total, offset, count and next_offset, and offset=next_offset gets the next page until it is null.
`list_triggers`	List Indigo triggers with their ID, name, enabled state, and plugin type information. Sorted by name, a page at a time: the reply says total, offset, count and next_offset, and offset=next_offset gets the next page until it is null.
`list_variable_folders`	List all variable folders for organization
`list_variables`	List variables with id, name and folder (when not in root). get_variable_by_id gives the value. Sorted by name, a page at a time: the reply says total, offset, count and next_offset, and offset=next_offset gets the next page until it is null.
`plugin_check`	Development checks on one plugin, keyed by check in the reply. A failing check does not stop the others. xml: parse Devices/Actions/Events/MenuItems/PluginConfig and apply Indigo’s naming rules (camelCase ASCII state ids, no spaces in an Actions uiPath, batteryLevel reserved). html: `node --check` every inline
`query_event_log`	Query Indigo server event log entries. Without after/before returns the most recent line_count entries. With after/before reads from the on-disk log files and returns all entries in that time window (useful for investigating past events). Time formats: ‘HH:MM:SS’ (today assumed), ‘YYYY-MM-DDTHH:MM:SS’ (full). The file scan covers at most 14 days, anchored on the END of the range: ‘before’ with no ‘after’ searches the 14 days leading up to it. The ‘range’ block in the reply reports the window actually scanned and sets span_clamped when the request was wider — so an empty result is never ambiguous. An inverted range (after >= before) is rejected, not answered with an empty list. source, contains and level filter the entries (ignoring case, all must hold) before line_count trims, so you get the newest N that match. With no after/before, a filter searches the last 24 hours.
`read_script`	Read the full content of a Python script from the Indigo Scripts folder.
`search_entities`	Search for Indigo entities using natural language. Results are slim by default (id, name, state, lastChanged). Use detail=’full’ only when you need complete device properties such as Z-Wave config or plugin props.
`server_info`	Facts about this Indigo server in one reply: install, Logs and database paths (to find the history DB and logs without typing a version number), the local web server URL, the Reflector’s URL and connection status (url is null when no Reflector is active), the configured latitude/longitude, and sunrise and sunset for date_iso (YYYY-MM-DD, default today).
`system_health`	Return a snapshot of Mac Mini system health: macOS version, Python version, disk usage (total/used/free/%), RAM summary, and uptime. No parameters required.
`variable_history`	One variable’s history from the SQLite SQL Logger (a PostgreSQL SQL Logger is not read). The logger writes a row only when the value changes, so the reply also gives value_before: the value in force when the window opened. Rows are newest first with ts in local time, and limit caps them from the newest end, so check truncated and ts_oldest. summary=true instead gives the number of changes and, per distinct value, how often it was set and how long it held in the window (share_of_window), plus min, max and a time-weighted mean when every value is a number — the way to answer ‘how long was it true today’. A deleted variable’s history can still be read by its old id.

Write tools (20)

Modify Indigo state. Require write (or admin).

Tool	Description
`action_execute_group`	Execute an action group, by ID or exact name
`all_devices`	Send one of Indigo’s native broadcasts: lights_on, lights_off or all_off. They reach native-protocol devices (Z-Wave/Insteon/X10) ONLY — devices owned by plugins (zigbee2mqtt, Shelly, Tasmota) are NOT affected, so switch those individually or through an action group.
`create_folder`	Create a device or variable folder. Returns the existing folder if one with the same name already exists (idempotent).
`device_control`	Control one device, by id or by name. action: on / off (optional delay, and duration to revert automatically — ‘fan on for 10 minutes’ is duration=600), toggle, brightness (value 0-100), brighten / dim (value = percentage points, more than 0), color (a ‘color’ hex code or CSS name such as ‘dodgerblue’, or red/green/blue 0-255, plus optional white 0-100 and white_temperature in Kelvin), status_request (poll the device), beep (to find it physically), ping (reachability), reset_energy (zero the kWh total — the old total is returned but cannot be restored). A name must match exactly or match one device confidently, otherwise nothing is switched and the candidates come back. The reset_energy action needs the admin scope.
`duplicate`	Duplicate a device, schedule or action group. new_name is optional — Indigo defaults to ‘Copy of '.
`enable_device`	Enable or disable a device’s communication. NOT the same as on/off — this controls whether Indigo polls/listens to the device at all.
`execute_schedule_now`	Execute a schedule immediately. ignore_conditions=True bypasses the schedule’s own conditions.
`fire_indigo_event`	Fire all Indigo Triggers of type ‘Claude Bridge → Claude Event’ with a structured payload. Use this to drive Indigo automations from a Claude tool call. Inside the user’s Trigger actions, the payload is available via Indigo’s event-data substitution %%e:”name”%%, %%e:”data”%%, %%e:”source”%%. Users filter on event name with a Script Condition testing event_data.get(‘name’).
`fire_trigger`	Execute a single Indigo trigger directly by ID or name (indigo.trigger.execute). Use this when you want to invoke a specific trigger’s actions without going through the event system used by fire_indigo_event.
`log_message`	Write a message to the Indigo on-screen event log (Log Viewer). The message appears immediately. Use for status updates, confirmations, or debug output that the user can see in the Indigo UI.
`move_to_folder`	Move a device, variable or trigger to a different folder. folder_id=0 means root.
`rename_device`	Rename a device.
`send_notification`	Send a Pushover push notification to the user’s own devices (the Pushover account set up in Indigo, and the caller cannot choose another recipient). Use for important alerts, confirmations, or proactive updates.
`set_enabled`	Enable or disable a trigger or schedule, by id or name. Optionally delay the change (delay_seconds) and/or revert it automatically after duration_seconds — e.g. silence a motion trigger for 30 minutes.
`speed_control`	Set a fan or speed-control device. Give exactly one of level (0-100 percent), index (0 off, 1 low, 2 medium, 3 high on a four-speed device, where the top index is the device’s speedIndexCount minus one) or step (+1 or -1 to move one index up or down). The reply gives the speed the device reports afterwards.
`sprinkler_control`	Drive a sprinkler device: run the programme, stop, pause, resume, next_zone, previous_zone, or set_zone with zone (1-based).
`thermostat_control`	Change a thermostat or TRV (e.g. RAMSES, Evohome). Give any combination of heat_setpoint, cool_setpoint, heat_delta, cool_delta (step up with a positive number, down with a negative one), hvac_mode and fan_mode. Temperatures are in the device’s own unit, as Indigo shows it, and a value outside a sane band for that unit is refused, never clamped. They are applied in that order and the reply lists what was done, with confirmed=false where the device has not reported the new value yet. The first failure stops the rest.
`update_automation`	Edit an automation’s basic fields and return before/after. Every kind: name and description. A trigger watching a device state or a variable can also have its event re-pointed: device_id, state_selector, state_change_type, state_value, variable_id, variable_change_type, variable_value (change types accept e.g. ‘becomes_true’, ‘becomes_false’, ‘changes’). Schedule timing, action steps and conditions cannot be edited through the API (Indigo UI only).
`variable_create`	Create a new variable
`variable_update`	Update a variable’s value

Admin tools (21)

Destructive / irreversible / code-execution / lifecycle / physical-security / data leaving the house. Require admin.

Tool	Description
`delete_automation`	Permanently delete a trigger, schedule or action group. Requires confirm=true AND the plugin’s delete preference to be enabled.
`delete_device`	Permanently delete a device. Destructive — cannot be undone. Requires confirm=true AND the plugin’s delete preference to be enabled.
`delete_folder`	Delete a device or variable folder by id or name. Refuses a non-empty folder unless delete_children=true, which deletes the devices or variables inside it — irreversible. Requires confirm=true AND the plugin’s delete preference to be enabled.
`delete_script`	Safely archive a Python script (moves to _backups/_archived/). Does not permanently delete — can be recovered manually.
`execute_client_menu_item`	Click any item in the Indigo client’s own menu bar, given the full path (e.g. path=[‘Interfaces’,’Z-Wave’,’Disable’]). Use this for the client commands that have no API at all — indigo.zwave has isEnabled() and no setter, so this is the only way to make Indigo release the Z-Wave stick for a controller backup. Pass list_only=true with a menu or submenu path (or [] for the menu-bar titles) to READ a menu instead of clicking it, which is how you find an item’s current label: several are toggles that rename themselves, and the Z-Wave one reads ‘Disable’ when on and ‘Enable’ when off. Listing does not bring the client to the front. Clicking does. Refuses Claude Bridge’s own submenu and Quit. Requires the Indigo GUI client running and System Events permission. ADMIN scope.
`execute_device_action`	Run a plugin’s own custom action from its Actions.xml — the actions that appear under Device -> Actions in the Indigo client, which no built-in tool can reach. Give device_id for a device action (Indigo marks those with deviceFilter) or plugin_id alone for a plugin-level action. props carries the action’s ConfigUI fields. The call is checked against the plugin’s Actions.xml first, so an unknown action id, a device action with no device, or a stopped owning plugin come back as errors — Indigo itself returns cleanly and does nothing in all three cases. A plugin action reports success by changing state, not by returning a value, so re-read the device to confirm the effect. The call waits at most 20 seconds: an action still going then comes back as timed out, and may still finish inside the plugin. Refuses Claude Bridge’s own actions. ADMIN scope: these actuate real hardware (valves, locks, doors, sprinklers).
`execute_indigo_python`	Run arbitrary Python in this plugin’s Indigo context. Has full access to the `indigo` module (devices, variables, triggers, thermostat.setHeatSetpoint, etc). mode=’exec’ runs a statement block and returns captured stdout/stderr. mode=’eval’ evaluates a single expression and returns its repr in ‘value’. ADMIN scope — treat as arbitrary code execution on the Indigo server. A run that takes longer than wait_seconds (default 5) keeps going in the background: the reply is {status: ‘running’, job_id}, and calling again with that job_id waits a little longer and returns the finished result. Only one run of this tool or its sibling can hold the output capture at a time, so another is refused at once, naming the running job. Results are kept 10 minutes.
`execute_plugin_menu_item`	Click a plugin’s menu item under the Indigo client’s Plugins menu (e.g. plugin_name=’Zigbee2MQTT Bridge’, menu_item_name=’Refresh Device Capabilities’). Uses AppleScript GUI scripting — requires the Indigo GUI client to be running and System Events permission granted. ADMIN scope.
`lock_control`	Lock or unlock a Z-Wave or other lock device. Indigo’s lock and unlock commands take no PIN. The reply says whether the lock has reported the new state yet (confirmed). ADMIN scope: this is physical security.
`plugin_refresh_deps`	Delete the pip-install success marker so Indigo re-runs requirements.txt on next plugin restart. restart=true also triggers the restart immediately (refused for Claude Bridge itself).
`raw_server_request`	Send a READ-ONLY raw named request to the Indigo server (indigo.rawServerRequest). Undocumented internal API — unsupported and may change between Indigo versions. Only ‘Get*’ request names are permitted, so mutating raw commands are not reachable. Example: name=’GetControlPage’, args={‘ID’: 12345, ‘GetPageFlags’: 65536}. Use 65536, NOT Indigo’s own FULL_PAGE_FLAGS (65538) — its second flag is ignore_actions, so 65538 withholds every element’s action and a page of working buttons reads as if nothing on it does anything. ADMIN scope: classified by what it can reach, not by today’s Get-only guard.
`remove_delayed_actions`	Cancel pending delayed actions. kind=’device’ cancels them for ONE device (e.g. a queued auto-off from device_control duration), leaving others alone. kind=’schedule’ does the same for one schedule, and kind=’trigger’ for one trigger. kind=’all’ removes every pending delayed action on the server — confirm with the user first.
`restart_plugin`	Restart an Indigo plugin, then wait (default 10 s, at most 20) for it to log ‘Started plugin’ and report started, running_version, error and warning counts and the lines it logged while restarting — no separate status check or log search needed. The wait holds Indigo’s web server, so it stops as soon as the plugin is up, and wait_seconds=0 returns at once. Errors a plugin logs later than a second after starting are not included. Refuses Claude Bridge itself — that kills the session asking. Restart it from the Indigo Plugins menu instead.
`run_script`	Execute a Python script from the Python Scripts folder in the Indigo Python context, with full access to the indigo module. Use for triggering automation logic, one-off tasks, or testing scripts. Returns stdout/stderr. A run that takes longer than wait_seconds (default 5) keeps going in the background: the reply is {status: ‘running’, job_id}, and calling again with that job_id waits a little longer and returns the finished result. Only one run of this tool or its sibling can hold the output capture at a time, so another is refused at once, naming the running job. Results are kept 10 minutes.
`send_email`	Send an email via Indigo’s configured SMTP device to any address. Use for detailed reports, logs, or non-urgent notifications. ADMIN scope: it sends data out of the house to a recipient the caller chooses.
`variable_delete`	Permanently delete a variable. Destructive — cannot be undone. Requires confirm=true AND the plugin’s delete preference to be enabled.
`webhook_create`	Register an OUTBOUND webhook: the home POSTs a signed JSON event to an APPROVED external URL when a device/variable condition is met. ADMIN. The target must be on the egress allow-list (default-deny — private/LAN ranges need an explicit CIDR opt-in). Returns a one-time HMAC signing key — capture it. Requires ‘Enable Event Webhooks’ in the plugin config.
`webhook_delete`	Delete an outbound webhook subscription by id. ADMIN.
`webhook_list`	List outbound webhook subscriptions with delivery-health stats. ADMIN. Secrets are redacted (signing key omitted, bearer token shown as ***).
`write_script`	Write a Python script in the Indigo Scripts folder. By default it overwrites an EXISTING script, taking a timestamped backup first, and refuses a missing one. create=true makes a NEW script instead and refuses one that already exists.
`zwave`	Manage the Z-Wave network. ADMIN. set_config_parameter: program a device (device_id, param_index, param_size = byte width 1, 2 or 4, param_value that fits that width, and wait_for_ack, which defaults to false since waiting holds the web server until the device answers) — tune motion sensitivity, report intervals and so on from the device manual’s parameter numbers. start_optimize: heal the mesh, the whole network or around device_id, and stop_optimize ends it. enter_inclusion: put the controller into inclusion mode to ADD hardware (use_encryption for S0), then the user presses the device’s pairing button. enter_exclusion: REMOVE a device. exit_inclusion_exclusion: cancel either mode. enter_exclusion cannot be undone, so it requires confirm=true AND the plugin’s delete preference to be enabled.