Domoticz MCP Server

Domoticz MCP Server

A Model Context Protocol (MCP) server for integrating with the Domoticz home automation system. This server provides tools to AI assistants (like Claude, Gemini, etc.) to view and control your smart home devices, scenes, user variables, and more.

Features

The server exposes Tools (for active control and modifications), Resources (for read-only contextual awareness), and Prompts (for guided interaction templates).

Tools (Actions)

• Device Control: Toggle switches, set states (On/Off), set dimmer levels, set thermostat temperatures, control blinds, and manage RGB/color lighting (brightness, hue, color temperature). Supports lookup by idx or name.
• Device Management: Create virtual sensors, rename devices, delete/hide devices, and manually update sensor values. Supports lookup by idx or name.
• Rooms and Scenes: Control scenes/groups. Get room devices by idx or room_name.
• User Variables: Read, add, update, and delete Domoticz user variables. Supports lookup by idx or name.
• History and Logs: Access device history graphs and text/light logs by idx or name. Retrieve system logs and add custom log messages.
• System Information: Get Domoticz instance version, global settings, hardware, sun times, users, and internal event scripts/rules.
• Security: Get and set the Domoticz security panel status.
• Notifications: Send notifications through the Domoticz notification subsystem.
• Event Management: Get, create, and update internal event scripts (Blockly, Lua, dzVents, Python).
• Cameras and Floorplans: Retrieve camera configurations and defined floorplans.

Resources (Context)

• domoticz://devices: Read the current state of all Domoticz devices.
• domoticz://device/{idx}, domoticz://device/{type}/{subtype}/{idx}, or domoticz://device/name/{name}: Read the current state of a specific device.
• domoticz://rooms: Read configured rooms (Room Plans).
• domoticz://room/{idx} or domoticz://room/{room_name}/{idx}: Read the full states of all devices within a specific room.
• domoticz://scenes: Read configured scenes.
• domoticz://scene/{idx} or domoticz://scene/name/{name}: Read the list of devices belonging to a specific scene.
• domoticz://user-variables: Read the list of all Domoticz user variables.
• domoticz://user-variable/{idx} or domoticz://user-variable/name/{name}: Read a specific Domoticz user variable.
• domoticz://events & domoticz://event/{event_id}: Read the overview and specific source code of event scripts.
• domoticz://log: Read the current Domoticz system log.
• domoticz://security: Read the current status of the security panel.
• domoticz://settings: Read global Domoticz settings and configuration.

Prompts (Templates)

• summarize_home: A prompt that instructs the AI to read the home state (devices, temperature, open doors) and provide a human-readable summary.
• troubleshoot_device: A template that asks for a device idx or name and instructs the AI to read the device state and system logs to diagnose issues.
• analyze_automations: Instructs the AI to review your internal event scripts for logic flaws or optimizations.

Prerequisites

• Python 3.10 or higher
• A running Domoticz instance
• Network access to the Domoticz API

Installation

Using `uv` (Recommended)

If you use uv, you can run the server directly from the source repository without installing it globally:

uv run --directory /path/to/domoticz-mcp domoticz-mcp

Standard Python Installation (Linux, macOS, Windows)

1. Clone or download this repository.
2. Navigate to the project directory.
3. Install the package using pip:

pip install .

This will install the domoticz-mcp command-line tool.

Configuration

The server requires configuration to connect to your Domoticz instance. These are provided as environment variables.

• DOMOTICZ_URL: The base URL of your Domoticz instance (e.g., http://192.168.1.100:8080). Defaults to https://xmpp.vanadrighem.eu/domoticz if not set.

Authentication Options

You can authenticate the MCP server with Domoticz using either an OAuth/API Token (Recommended) or Basic Auth.

Option 1: OAuth / API Token (Recommended)

This approach uses an OAuth2 token and is generally more secure, as you can revoke the token at any time without changing your password. The server supports an interactive authentication flow so you do not need to provide your username and password in the configuration.

1. In the Domoticz UI, go to Setup -> More Options -> Applications.
2. Click Add Application and configure:
   • Name: e.g., MCP Server
   • isPublic: Check this if you want to use Key-Pair, or leave unchecked for a Shared Secret.
3. Note the generated Client ID and **C