uc-remote-mcp

Allow an activity or macro to use more entities. Exposing an entity from an integration is not enough on its own — it must also be added here before a button or page item can use it. Existing entries are preserved.

Answer the current setup screen and return the next. Send every field the screen asks for; a rejected step ends the flow and it must be restarted.

Dump the entire remote configuration (system, entities, activities, remote-entities, UI pages — full detail) to one JSON file. Defaults to %APPDATA%/uc-remote-mcp/backups/.json, keeping the last 50.

Set the same button binding across many activities at once (e.g. route VOLUME_UP on every activity to the AVR). Filter with activity_ids and/or name_contains; no filter = all activities. Invalid activities are skipped with a reason. One backup before the batch. Defaults to dry_run=True (returns the full per-activity plan); set dry_run=false to apply.

Abandon an in-progress setup flow, changing nothing.

Expose entities from an integration so activities and pages can use them. Additive; removes nothing. Setup finishing does not do this for you.

Answer a confirmation screen ("press the button on the device, then continue") and return the next one. Use answer_integration_setup for screens with fields; this is for the ones without.

Create an activity — a "device" on the remote's home screen.

Pass entity_ids to build from scratch, or clone_from to copy an existing activity/macro/remote-entity; not both. icon takes "uc:name" or "custom:file.png". The empty page the remote creates alongside it is removed, and the result says if it joined the default activity group, which can make its tile power devices on and off.

Add a new page to an activity or remote-entity. scope is "activity" or "remote". grid is {"width": N, "height": M}; items use the same shape as get_ui_page returns. The page is appended last; reorder with set_default_ui_page. Every item command is validated first.

Remove a driver, its instance and all its entities. Also strips every button mapping and page item that used them. Read the preview before applying.

Remove one configured instance and its entities, keeping the driver. The teardown for firmware-shipped drivers. Also strips every button mapping and page item that used those entities — read the preview.

Delete a UI page from an 'activity' or 'remote'. IRREVOCABLE on the device — the auto-backup taken before the write is the only way back. Dry-run (default) shows the full page content that would be lost.

Show what changed between the current live config and a backup file (read-only). Reports the operations a restore would perform plus differences that cannot be restored.

Scan the LAN via mDNS for UC remotes. Returns a list of {name, host, port, model, fw, id}.

Full activity config: included entities, on/off power sequences, button overrides, and the list of UI pages.

Physical-button -> command bindings. scope is 'activity' (needs scope_id=activity_id), 'remote' (needs scope_id=remote entity_id), or 'device' (needs scope_id=target entity_id; returns every binding across all activities and remotes that targets that device).

Full config for one device (entity): features, available commands, current attributes, and options.

One integration instance in full, including the entities it has configured.

The current screen of a setup flow. 404 means no flow is in progress.

Return model, firmware, battery level/status, and currently active activities. Uses the first configured remote if host is not specified.

Items on one UI page: grid size and each item's position, type, and command. Identify the page by its parent scope ('activity'/'remote'), the scope's entity_id, and the page_id (from list_ui_pages).

Install a custom driver from a .tar.gz archive on this machine. There is no in-place update: delete the old driver first. Restart the system afterwards or its setup flow will not start.

List all activities with id, name, state, description, and included entities.

Commands a device exposes, for picking when mapping buttons. Returns {features, simple_commands}.

List all configured devices (entities). Each physical device may appear as several entities (e.g. a TV has both a media_player and a remote entity). Optionally filter by entity_type (media_player, remote, light, switch, sensor). Returns {id, name, type, integration, device_class, state} per entity.

Entities an integration offers. only_new re-polls the integration and lists what is not exposed yet, which is required after pairing a new device.

Installed integration drivers and their configured instances.

device_state is not a health signal: an instance reports CONNECTED while its entities are stale. Check the entities too.

Entities an activity or macro is currently allowed to use. scope is "activity" or "macro" — both keep their own list, and a command naming an entity outside it is rejected.

List UI pages for a scope: 'activity' or 'remote'. scope_id is that entity's id. Returns page ids, names, grids, and item counts.

Stop an activity or macro using entities. Every button mapping and page item referencing them is removed too, so read the preview before applying.

Disable and re-enable an integration. The usual fix when devices stop responding but the integration still claims to be connected.

Restart the remote's "ui", "core", or "system". Sends no device commands and changes no configuration. "ui" is how configuration changes are made to repaint; "system" is required after installing a driver.

Restore activities/remotes customization (names, button mappings, UI pages, sequences) from a backup file. First call returns a confirmation_token + full plan without writing; call again with the token and dry_run=false to apply. Auto-backup of the current state is taken before applying.

Fire a one-off command at a device (entity). Transient (does not change saved config) but affects the device, so defaults to dry_run=True. Set dry_run=false to actually send. Body: PUT /entities/{id}/command {cmd_id, params?}.

Set one physical-button -> command binding on an 'activity' or 'remote'. entity_id is REQUIRED for activities (the command target) and ignored for remotes. Defaults to dry_run=True (shows before/after); auto-backs-up before any real write. Set dry_run=false to apply.

Make a page the first/default page of an 'activity' or 'remote' UI (the page shown when it opens). Implemented as a page reorder — the API has no explicit default-page property. Defaults to dry_run=True.

Enable or disable an integration instance.

First-run setup. Authenticate with admin PIN, create a long-lived API key, and save config. Only needed once per remote.

Begin an integration's setup and return its first screen.

Some drivers require a value up front (usually an API key) and answer "400 Setup data not provided for field: X" without it — pass setup_data={"X": "..."}. A 503 means the driver process is not running yet, which is normal right after installing: restart the system first.

Replace an activity's on and/or off power sequence. Steps are {"type":"command","command":{"entity_id","cmd_id","params"?}} or {"type":"delay","delay":}. Omitted sequence = unchanged; empty list clears it. Command steps are validated against the activity's included entities. Defaults to dry_run=True; auto-backup before any real write.

Update a UI page's name, grid, and/or items on an 'activity' or 'remote'. Omitted fields stay unchanged; an EMPTY items list clears the page. Item commands are validated against the scope before writing. Defaults to dry_run=True; auto-backup before any real write.