switch_scene
Turn a scene or group on, off, or toggle it using its IDX or name in Domoticz. 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:672-683 (handler)The handler function for the 'switch_scene' MCP tool. Validates that idx or name is provided, validates command is 'On', 'Off', or 'Toggle', resolves the scene idx (by idx or by name), and calls the Domoticz API with param=switchscene.
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:671-671 (registration)The @mcp.tool() decorator registers the switch_scene function as an MCP tool on line 671.
@mcp.tool() - src/domoticz_mcp/server.py:673-673 (schema)Docstring/type hints define the schema: 'command' (str: On/Off/Toggle), 'idx' (optional int), 'name' (optional 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 idx from either a direct idx or a name lookup, using _resolve_idx with 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 _resolve_idx helper that either passes through a provided idx or looks up an entity by name in 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