MCP model context protocol LLM

Note: This page is maintained in the Domoticz GitHub repository. Please do not edit it directly on the Wiki.

Last revised: 2026-05-01 · Domoticz 2026.1 build 17858

Domoticz (from version 2026.1) adds built-in support for the Model Context Protocol (MCP), allowing AI assistants and LLM clients to monitor and control your home automation system directly — without any external intermediary process.

Only MCP specification version 2025-06-18 is supported.

Streamable HTTP transport is supported, including persistent SSE streams for real-time async notifications. STDIO transport is not natively supported; use an HTTP proxy if your client requires it.

Enabling MCP support

MCP is enabled by default. To disable it, start Domoticz with the -nomcp flag:

./domoticz -nomcp

A status message in the log will confirm whether MCP support is active.

Authentication & Security

The MCP endpoint at /mcp is subject to the same security rules as the rest of Domoticz. You have two options:

Option 1: Private Network (no credentials)

If the AI client runs inside the IP range defined in Domoticz's Security Settings (Setup → Settings → Security → Local Networks), no authentication is required. This is the simplest setup for a local LAN.

Option 2: Access Token

An Access Token is a long-lived JWT that you create once in the Domoticz UI and paste into your AI client's configuration. No separate user account is needed — the token carries its own rights.

See Creating an Access Token below for step-by-step instructions.

Once you have a token, pass it as a Bearer token in the Authorization header:

Authorization: Bearer <your access token>

See the client-specific examples below for how to configure this in each client.

Creating an Access Token

Access Tokens are managed under Setup → More Options → Access Tokens.

1. Click Create Access Token
2. Enter a descriptive Name (e.g. Claude Desktop or VS Code MCP)
3. Choose the Rights level:
   • Viewer — read-only access (sensor values, status queries, history)
   • User — can also control devices, scenes, and user variables
   • Admin — full access including hardware, settings, events, and user management
4. Choose an Expiry (30 days, 90 days, 1 year, or Never)
5. Click Create — the token is displayed once. Copy it immediately and store it securely; it cannot be retrieved again.

To revoke a token at any time, return to Setup → More Options → Access Tokens and click Delete.

Tip: Use the minimum rights level needed for the intended client. For read-only dashboards or monitoring tools, choose Viewer. For full home-automation control, choose User or Admin.

Connecting AI clients

Claude Desktop

Claude Desktop currently only supports STDIO transport for standard users. Use mcp-proxy as an intermediary to bridge STDIO ↔ Streamable HTTP.

Installing mcp-proxy on Windows

1. Download and install Claude Desktop from claude.ai/download.
2. Install the uv Python package manager. In PowerShell:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Install mcp-proxy with uv:

   uv tool install mcp-proxy

4. Find the full path of mcp-proxy.exe — you will need it in the configuration below:

   where.exe mcp-proxy

5. Open the Claude Desktop configuration folder:

   %APPDATA%\Claude

   If the folder or claude_desktop_config.json file does not exist yet, start Claude Desktop once and enable Developer Mode from the menu, or create the file manually.

6. Edit claude_desktop_config.json as shown below, replacing the command value with the path returned by where.exe mcp-proxy.

Installing mcp-proxy on Linux / macOS

Install uv (curl -LsSf https://astral.sh/uv/install.sh | sh), then run uv tool install mcp-proxy and use which mcp-proxy to find the binary path. The Claude Desktop configuration file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS.

Configuration

Add the following to your Claude Desktop configuration file (claude_desktop_config.json).

Without Access Token (client is within the private network range):

{
  "mcpServers": {
    "domoticz": {
      "command": "/path/to/mcp-proxy.exe",
      "args": ["--transport", "streamablehttp", "http://<domoticz_ip>:<domoticz_port>/mcp"]
    }
  }
}

With Access Token:

{
  "mcpServers": {
    "domoticz": {
      "command": "/path/to/mcp-proxy.exe",
      "args": ["--transport", "streamablehttp", "http://<domoticz_ip>:<domoticz_port>/mcp"],
      "env": {
        "API_ACCESS_TOKEN": "<your access token>"
      }
    }
  }
}

Create an Access Token under Setup → More Options → Access Tokens and paste it as the API_ACCESS_TOKEN value. See Creating an Access Token above.

Note: Pro and Max Claude users may have access to remote MCP support, in which case you can connect directly using the URL http://<domoticz_ip>:<domoticz_port>/mcp without a proxy.

Claude Code (CLI)

Run these commands once in a terminal — Claude Code stores the server in its configuration automatically.

Add the server:

claude mcp add --transport http domoticz http://<domoticz_ip>:<domoticz_port>/mcp

If authentication is required (client outside the private network range), pass your Access Token as a header:

claude mcp add --transport http domoticz http://<domoticz_ip>:<domoticz_port>/mcp --header "Authorization: Bearer <your access token>"

Remove the server:

claude mcp remove domoticz

Visual Studio Code

VS Code has built-in MCP support. Open the Command Palette (View → Command Palette or Ctrl+Shift+P) and choose MCP: Add Server..., or edit your settings directly.

Without Access Token (client is within the private network range):

{
  "servers": {
    "domoticz": {
      "type": "http",
      "url": "http://<domoticz_ip>:<domoticz_port>/mcp"
    }
  }
}

With Access Token:

{
  "servers": {
    "domoticz": {
      "type": "http",
      "url": "http://<domoticz_ip>:<domoticz_port>/mcp",
      "headers": {
        "Authorization": "Bearer <your access token>"
      }
    }
  }
}

To use Visual Studio Code with a remote MCP server, open the Command Palette (View → Command Palette or Ctrl+Shift+P) and choose MCP: Add Server....

This creates a mcp.json file located at %APPDATA%\Code\User\mcp.json on Windows. Configure it as shown below:

{
  "servers": {
    "domoticz": {
      "url": "https://YourDomain:YourPort/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer TokenID"
      }
    }
  },
  "inputs": []
}

To create the TokenID:

• Create an application in Domoticz with application name domoticzmcp and a client secret of your choice.
• Create a user in Domoticz (e.g. name MCP) with a password of your choice.

Then run:

curl --location --request POST 'https://YourDomain:YourPort/oauth2/v1/token?client_id=domoticzmcp&client_secret=YourClientSecret&username=MCP&password=YourPWD&grant_type=password'

The response will contain:

{
  "access_token": "TokenID",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use the access_token value as the TokenID in your mcp.json.

When starting the MCP server in Visual Studio Code, the application prompts you to provide the application name and client secret, then opens the Domoticz login page where you enter the MCP user credentials.

Gemini CLI

Add to ~/.gemini/settings.json under mcpServers.

Without Access Token (client is within the private network range):

{
  "mcpServers": {
    "domoticz": {
      "type": "http",
      "url": "http://<domoticz_ip>:<domoticz_port>/mcp"
    }
  }
}

With Access Token:

{
  "mcpServers": {
    "domoticz": {
      "type": "http",
      "url": "http://<domoticz_ip>:<domoticz_port>/mcp",
      "headers": {
        "Authorization": "Bearer <your access token>"
      }
    }
  }
}

Other MCP clients

Any MCP-compatible client that supports Streamable HTTP transport can connect to:

http://<domoticz_ip>:<domoticz_port>/mcp

Add an Authorization: Bearer <access token> header if the client is outside the private network range. Create a token under Setup → More Options → Access Tokens.

Resources

Resources provide read-only context that AI clients can subscribe to or read on demand.

Aggregate resources

The following named resources expose a summary of each subsystem:

URI	Description
domoticz://devices	All used devices (name, type, current value)
domoticz://rooms	All configured rooms/plans
domoticz://scenes	All scenes and groups with their status
domoticz://user-variables	All user-defined variables
domoticz://events	All automation event scripts (name, interpreter, status)
domoticz://security	Current security panel status
domoticz://settings	Key system configuration values
domoticz://log	Recent system log entries
domoticz://sensor-types	All sensor types available for create_virtual_sensor, with their names and numeric mapped values
domoticz://hardware	All configured hardware instances with type, enabled status, and ID
domoticz://notifications	All configured device notifications with trigger conditions and target systems
domoticz://timers	All device and scene timers with schedule and command details

Per-item resources

Individual items can be addressed with these URI patterns:

URI pattern	Description
domoticz://device/{idx}	A single device by its numeric IDX
domoticz://room/{idx}	All devices assigned to a room
domoticz://scene/{idx}	Devices and commands belonging to a scene
domoticz://user-variable/{idx}	A single user variable by IDX
domoticz://event/{id}	The source code of an event script
floorplan:///image/{idx}	A floorplan image (PNG/JPEG/SVG) by IDX

Tools

Tools are actions an AI agent can invoke. All tools accept and return plain text so they work with any LLM.

Device discovery

Tool	Parameters	Description
search_devices	query (required), filter (optional: light/temp/weather/utility)	Case-insensitive substring search across device name, type and subtype. Returns name, type, current value, idx, battery level (if applicable), and signal level/RSSI (if applicable). Use this first to discover the exact name of a device before calling other tools.
get_all_devices	filter (optional: light/temp/weather/utility), hw_idx (optional, integer), include_unused (optional, boolean)	Return a list of devices, optionally filtered by category, hardware adapter IDX, or inclusion of unused/disabled devices. Each entry includes name, type, current value, idx, battery level (if applicable; 255 = no battery), and signal level/RSSI (if applicable).
get_device	name or idx (at least one required)	Return full details for a single device, including hardware, type, current value, last update, battery level (if applicable), and signal level/RSSI (if applicable).

Switch & sensor control

Tool	Parameters	Description
get_switch_state	switchname or idx (one required)	Get the current on/off state of a switch by name or IDX.
toggle_switch_state	switchname or idx (one required)	Toggle a switch between on and off.
set_switch_state	switchname or idx (one required), state (required: On/Off)	Explicitly set a switch to On or Off. State is case-insensitive.
get_sensor_value	sensorname or idx (one required)	Get the current reading of any sensor by name or IDX.
set_setpoint_value	thermostatname or idx (one required), setpoint (required, number)	Set the target temperature setpoint of a thermostat.

Dimmer & lighting control

Tool	Parameters	Description
set_dimmer_level	switchname or idx (one required), level (required, 0–100)	Set a dimmable light to a specific brightness level.
set_color_brightness	switchname or idx (one required), hue (required, 0–360), brightness (required, 0–100), iswhite (optional, boolean)	Set the colour and brightness of an RGB light.
set_color_temperature	switchname or idx (one required), kelvin (required, 2700–6500)	Set the colour temperature of a tunable-white light in Kelvin. 2700K is warm white, 6500K is cool daylight.

Blind & shutter control

Tool	Parameters	Description
control_blinds	switchname or idx (one required), command (required: Open/Close/Stop)	Send an Open, Close or Stop command to a blind or shutter. Command is case-insensitive.

Scene & room control

Tool	Parameters	Description
get_scenes	—	List all scenes and groups with their current status.
switch_scene	scenename or scene_id (one required), command (required: On/Off)	Activate or deactivate a scene or group by name or IDX.
get_rooms	—	List all configured rooms (plans).
get_room_devices	roomname or room_id (one required)	List all devices assigned to a specific room.
get_scene_devices	scenename or scene_id (one required)	List the devices and commands that make up a specific scene.

Device management

Tool	Parameters	Description
rename_device	name or idx (one required), new_name (required)	Rename a device.
delete_device	name or idx (one required)	Hide a device (sets Used=0; does not permanently delete data).
create_virtual_sensor	hw_idx (required), sensorname (required), sensortype (required, integer)	Create a new virtual sensor on a virtual hardware adapter. Common sensor types: 80=Temperature, 81=Humidity, 5=Text, 6=Switch, 113=Counter.
update_device_value	name or idx (one required), nvalue (required, integer), svalue (optional, string)	Directly update the value of a device (useful for virtual sensors).

History

Tool	Parameters	Description
get_sensor_history	name or idx (one required), days (optional, default 7), start_date / end_date (optional, YYYY-MM-DD), count (optional, 1–500)	Retrieve history for any device or scene. For sensors (temperature, humidity, barometer, rain, wind, UV, percentage, fan, P1 smart meter, energy/kWh, gas, water, counters): returns daily aggregated min/avg/max calendar data. Specify days for a trailing window or start_date+end_date for a custom range. For switches and scenes: returns on/off/dim event log entries from LightingLog. Use count for the last N events regardless of date, or days/start_date+end_date for a date-filtered log.
get_sensor_short_log	name or idx (one required), hours (optional, 1–168, default 24), count (optional, 1–1000)	Retrieve recent high-resolution measurements at ~5-minute intervals. Use this for today's data, the last 24 hours, or the last N readings. Short-log data is kept for a configurable number of days (default: 1 day). Not applicable to switches or scenes — use get_sensor_history for multi-day or long-term data.

User variables

Tool	Parameters	Description
get_user_variables	—	List all user-defined variables with their current values and types.
add_user_variable	name (required), vtype (required, 0–4), value (required)	Create a new user variable. Types: 0=Integer, 1=Float, 2=String, 3=Date (DD/MM/YYYY), 4=Time (HH:MM).
update_user_variable	name or variable_id (one required), value (required), vtype (optional)	Update an existing user variable's value (and optionally its type).
delete_user_variable	name or variable_id (one required)	Delete a user variable by name or IDX.

System information

Tool	Parameters	Description
get_status	—	System overview: version, build, uptime, active device/hardware/scene counts, and sunrise/sunset times.
get_hardware	—	List all configured hardware adapters with their type, address and enabled status.
get_settings	—	Return key system configuration values (title, location, temperature scale, language, etc.).
get_sun_times	—	Full solar data for today: sunrise, sunset, dawn, dusk, solar noon, civil/nautical twilight times and day length.
get_cameras	—	List all configured cameras (name, address, port, enabled status — no credentials).
get_floorplans	—	List all available floorplans by name and IDX (use get_floorplan to retrieve the actual image).
get_floorplan	floorplan or floorplan_id (one required)	Retrieve a floorplan image by name or IDX (returned as base64-encoded image data).
get_users	—	List system users with their username, rights level and active status (no password information).

Logging & notifications

Tool	Parameters	Description
get_logging	logdate (optional, Unix timestamp)	Retrieve system log messages, optionally filtered to entries since a given timestamp.
add_log_message	message (required), level (optional: normal/status/error, default: normal)	Write a message to the Domoticz system log. Entries are prefixed with MCP: for identification.
send_notification	subject (required), body (required), priority (optional, −2 to 2, default: 0)	Send a push notification through all configured Domoticz notification services. Use sparingly.

Security panel

Tool	Parameters	Description
get_security_status	—	Get the current state of the security panel: Disarmed, Armed Home, or Armed Away.
set_security_status	status (required, 0=Disarmed/1=Armed Home/2=Armed Away), seccode (required)	Change the security panel state. Requires the security PIN configured in Domoticz Setup → Settings → Security.

Event/automation scripts

Tool	Parameters	Description
get_events	—	List all automation event scripts with their interpreter (dzVents/Lua/Python/Blockly) and enabled status.
get_event	event_name or event_id (one required)	Retrieve the full source code of a specific event script by name or IDX.
create_event	name (required), interpreter (required: Lua/dzVents/Python/Blockly), code (required), enabled (optional, default: true)	Create a new automation event script.
update_event	event_name or event_id (one required), code (optional), enabled (optional), new_name (optional)	Update an existing event script's code, enabled state, or name.
delete_event	event_name or event_id (one required)	Permanently delete an event script by name or IDX. This cannot be undone.

Prompts

Prompts are pre-written instruction templates that guide the AI through common tasks. Select a prompt from your MCP client's interface to get started.

Prompt	Arguments	Description
housesummary	room (optional)	Summarize the current status of all sensors and devices in the house, grouped by room. Optionally limit the summary to a specific room.
systemanalysis	—	Analyze the current status of the system and provide insights.
troubleshoot_device	device (required)	Ask the AI to diagnose a specific device by checking its state, recent history, system logs, and hardware status.
analyze_automations	—	Review all event scripts for logic issues, inefficiencies, or improvement opportunities.
analyze_event	event (required)	Review a specific event script for logic issues, inefficiencies, or improvement opportunities.
energy_report	—	Summarize power and energy consumption across all electric sensors, identify high consumers, and compare to recent history.
security_check	—	Review security panel status, door/window sensors, cameras, and recent alerts.
battery_status	—	List all battery-powered devices, flag low-battery ones, and suggest replacements.
climate_overview	—	Summarize temperature, humidity, and thermostat setpoints per room and suggest comfort improvements.
scene_optimizer	—	Review all scenes and groups, identify redundant or conflicting ones, and suggest consolidation.
hardware_health	—	Check all hardware instances for connectivity and errors, and flag anything offline or problematic.
create_automation	rule (required)	Guide through creating a new dzVents event script for a described automation rule.
daily_report	—	Generate a daily digest covering overnight anomalies, battery warnings, offline devices, and energy highlights.

Async notifications (SSE)

Domoticz supports the full MCP Streamable HTTP transport, including server-sent event (SSE) streams for real-time push notifications. This allows AI clients such as VS Code Copilot to stay current on device state without polling.

How it works

After calling initialize, the server returns an Mcp-Session-Id header. The client then opens a persistent SSE stream with:

GET /mcp HTTP/1.1
Accept: text/event-stream
Mcp-Session-Id: <session-id>
MCP-Protocol-Version: 2025-06-18

The server keeps this connection open and pushes JSON-RPC notification events as they occur. The client must include Mcp-Session-Id on all subsequent POST requests to associate them with the correct session.

Notification types

Notification	Trigger
notifications/resources/updated	A device or scene state changed. The params.uri field contains the resource URI, e.g. domoticz://devices/42 or domoticz://scenes/3.
notifications/resources/list_changed	A device was added or removed (virtual sensor created, device deleted, hardware added/removed).
notifications/tools/list_changed	Same trigger as above — the tool list changes whenever the device list changes.
notifications/message	A Domoticz error log entry, or an MCP-specific operational message (e.g. SSE stream connected). See Log forwarding below.

Resource subscriptions

By default a session receives notifications/resources/updated for all device and scene changes. To restrict notifications to specific resources, send a resources/subscribe request:

POST /mcp
{
  "jsonrpc": "2.0", "id": 1,
  "method": "resources/subscribe",
  "params": { "uri": "domoticz://devices/42" }
}

Once any subscription is registered, only events matching a subscribed URI are sent. Use resources/unsubscribe with the same body to remove a subscription.

Log forwarding

By default, only Domoticz LOG_ERROR messages are forwarded as notifications/message events. MCP-specific operational messages (such as "SSE stream connected") are always sent regardless of the log level setting.

Clients can adjust the log level via logging/setLevel:

POST /mcp
{
  "jsonrpc": "2.0", "id": 2,
  "method": "logging/setLevel",
  "params": { "level": "error" }
}

Valid levels are debug, info, notice, warning, error, critical, alert, emergency. Note: to prevent flooding, the minimum effective level is always error — requesting debug or info has no additional effect.

Reconnection and event replay

Each SSE event carries a numeric id: field. If a client disconnects and reconnects, it can send a Last-Event-ID header to replay any events it missed (up to the last 100 events, or events from the last 5 minutes):

GET /mcp HTTP/1.1
Accept: text/event-stream
Mcp-Session-Id: <session-id>
Last-Event-ID: 17

Session lifecycle

Sessions are created by initialize and terminated by:

• A DELETE /mcp request with the Mcp-Session-Id header
• Automatic pruning after 1 hour of inactivity

Notes and limitations

• Only MCP specification version 2025-06-18 is supported.
• Streamable HTTP transport is implemented, including SSE streams for async notifications. STDIO is not natively supported; use an HTTP proxy if your client requires it.
• All tool responses are plain text, making them compatible with any LLM regardless of multimodal support (except get_floorplan which returns image data).
• SSE sessions are pruned after 1 hour of inactivity. Long-running AI agents should periodically send a request to keep the session alive.
• The minimum log forwarding level is error. Status and debug messages from Domoticz are intentionally not forwarded to avoid flooding AI clients during normal operation.
• The send_notification tool sends to real devices (phone, email, etc.). Avoid invoking it in automated loops.
• The delete_device tool hides a device (sets Used=0) rather than permanently deleting it. Historical data is preserved.
• The create_event and update_event tools take effect immediately — the event system reloads after each change.
• Device and scene names passed to tools are matched exactly (case-sensitive). All tools that accept a name also accept a numeric idx parameter as an alternative — use whichever is more convenient. Command values like On/Off/Open/Close are normalised automatically (case-insensitive).
• Signal level (RSSI) is reported for wireless devices as rssi=<value> (compact format in list tools) or SignalLevel: <value> (detail format in get_device). The value 12 is the default/unknown value and is omitted from output.