switch_scene
Turn a Domoticz scene or group On, Off, or Toggle using its IDX or name. Scenes support only On command.
Instructions
Turn a scene or group On or Off by IDX or Name in Domoticz. command must be 'On', 'Off', or 'Toggle'. Scenes can only be turned 'On'.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| idx | No | ||
| name | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/domoticz_mcp/server.py:665-677 (handler)The main handler function for the 'switch_scene' tool. Decorated with @mcp.tool(), it accepts a command ('On', 'Off', 'Toggle'), an optional idx, and an optional name. It resolves the scene idx (via name if needed), then calls the Domoticz API with 'switchscene' parameter.
@mcp.tool() async def switch_scene(command: str, idx: int | None = None, name: str | None = None) -> str: """Turn a scene or group On or Off by IDX or Name in Domoticz. command must be 'On', 'Off', or 'Toggle'. Scenes can only be turned 'On'.""" if idx is None and name is None: return '{"status": "error", "message": "Must provide either idx or name"}' if command.capitalize() not in ['On', 'Off', 'Toggle']: return '{"status": "error", "message": "command must be \'On\', \'Off\', or \'Toggle\'"}' async with create_client() as client: resolved_idx = await _resolve_scene_idx(client, idx, name) if resolved_idx is None: return '{"status": "error", "message": "Scene not found"}' response = await _do_request(client, "GET", f"{DOMOTICZ_API_URL}?type=command¶m=switchscene&idx={resolved_idx}&switchcmd={command.capitalize()}") return response.text - src/domoticz_mcp/server.py:665-665 (registration)The tool is registered via the @mcp.tool() decorator on the switch_scene async function at line 665.
@mcp.tool() - src/domoticz_mcp/server.py:666-667 (schema)The schema/type definition for switch_scene parameters: command (str), idx (int | None), name (str | None). The docstring defines the command as 'On', 'Off', or 'Toggle'.
async def switch_scene(command: str, idx: int | None = None, name: str | None = None) -> str: """Turn a scene or group On or Off by IDX or Name in Domoticz. command must be 'On', 'Off', or 'Toggle'. Scenes can only be turned 'On'.""" - src/domoticz_mcp/server.py:378-380 (helper)Helper function _resolve_scene_idx used by switch_scene to resolve a scene's idx from either a direct idx or a name lookup via the scene cache.
async def _resolve_scene_idx(client: "httpx.AsyncClient", idx: Optional[int] = None, name: Optional[str] = None) -> Optional[int]: """Resolve a scene to its idx.""" return await _resolve_idx(client, idx, name, _scene_cache, f"{DOMOTICZ_API_URL}?type=command¶m=getscenes") - src/domoticz_mcp/server.py:354-370 (helper)Generic helper _resolve_idx that resolves an entity's idx by either direct idx or name lookup from cached API data.
async def _resolve_idx( client: "httpx.AsyncClient", idx: Optional[int], name: Optional[str], cache: Dict[str, Any], api_url: str ) -> Optional[int]: """Resolve an entity to its idx by either using the provided idx or looking up by name.""" if idx is not None: return idx if not name: return None items = await _get_cached_data(client, cache, api_url) for item in items: if item.get("Name", "").lower() == name.lower(): return int(str(item.get("idx"))) return None