The Domoticz MCP Server lets AI assistants view, control, and manage a Domoticz smart home system through a comprehensive set of tools.
Device Discovery & Search
Get a high-level system overview with device counts, search devices by name/status (substring/regex), get all devices and their states, or look up a specific device by IDX or name.
Device Control
Toggle switches/lights, set On/Off states, adjust dimmer levels (0–100), set thermostat temperatures (Celsius), control blinds (Open/Close/Stop), set RGB color/brightness, and set color temperature for white-spectrum lights.
Device Management
Rename, delete, or hide devices; create virtual sensors; and manually update sensor/device values.
Scenes & Rooms
List all scenes/groups, turn a scene On/Off/Toggle, view devices in a scene, list all rooms, and get devices within a specific room.
User Variables
Get, add, update, and delete user variables (integer, float, string, date, time).
Maintenance & Health
List devices with low battery levels, identify devices that haven't checked in within a timeframe, and check hardware gateway health.
Energy Analytics
Summarize today's energy usage across all power-reporting devices.
History & Logs
Retrieve device history/graph data, access system logs (including filtered error logs), and add custom log messages.
Event / Automation Scripts
Get an overview of all event scripts, view source code of a specific script, create new scripts (Lua, dzVents, Python, Blockly), update existing scripts, and search inside script source code.
System Information
Get Domoticz version/build info, global settings, configured hardware/gateways, sunrise/sunset times, user accounts, cameras, and floorplans.
Security
Get and set the security panel status (Disarm, Arm Home, Arm Away).
Notifications
Send custom notifications through Domoticz's notification subsystem.
Advanced
Execute generic Domoticz API calls directly for anything not covered by the above tools.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Domoticz MCP Server turn on the living room lights and set the thermostat to 21 degrees"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
The server exposes Tools (for active control and modifications), Resources (for read-only contextual awareness), and Prompts (for guided interaction templates).
Search: search_devices_tool searches devices by name or current data/status text. search_scripts_tool searches inside Domoticz event scripts.
Authentication: start_oauth_login starts a short-lived login and opens the authorization page locally without returning transaction data. get_oauth_login_status reports when the login is complete.
Energy History: get_daily_energy_history, get_weekly_energy_history, and get_monthly_energy_history read counter graph history for energy, gas, and water meters by idx or name.
Device Control: toggle_switch, set_switch_state, set_dimmer_level, set_temperature_setpoint, control_blinds, set_color_brightness, and set_color_temperature control supported devices by idx or name.
Device Management: rename_device, delete_device, create_virtual_sensor, and update_device_value manage devices and virtual sensors.
Scenes and Groups: switch_scene activates configured scenes/groups by idx or name.
User Variables: add_user_variable, update_user_variable, and delete_user_variable manage Domoticz user variables.
Event Scripts: create_event and update_event create or update internal Domoticz event scripts.
System Actions: restart_system, add_log_message, send_notification, and set_security_status call Domoticz system, log, notification, and security APIs.
Advanced: call_domoticz_api executes a generic Domoticz command API call and returns only its sanitized status/title.
High-impact tools require confirm=True: call_domoticz_api, delete_device, delete_user_variable, update_event, restart_system, and set_security_status.
domoticz://dashboard: Read a curated view of favorite and currently active devices (lights on, sensors active).
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. In the typed form, idx is authoritative and type/subtype are descriptive path fields.
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 a specific scene/group entry.
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://logs or domoticz://log: Read the current Domoticz system log.
domoticz://logs/error: Read a filtered view containing only 'Error' level entries from the log.
domoticz://security: Read the current status of the security panel.
domoticz://settings: Read a reviewed, non-sensitive subset of global display/version settings.
domoticz://hardware: Read only gateway idx, name, type, and enabled status. Connection details and integration configuration are omitted.
domoticz://docs/dzvents_syntax: Cheat sheet for writing dzVents automation scripts.
domoticz://docs/blockly_syntax: Syntax rules for Blockly XML automations.
agent_guidance: Orients an AI agent to start with domoticz://overview, prefer idx, and use health/log resources for troubleshooting.
summarize_home: Guides a concise home-state summary from domoticz://dashboard.
maintenance_report: Guides a health check using battery alerts, system health, and error logs.
energy_audit: Guides an energy review using domoticz://devices and the energy history tools.
Related MCP server: Indigo MCP Server Plugin
Caching: The server implements a 5-minute TTL cache for devices, scenes, user variables, and rooms to significantly reduce API latency and Domoticz load.
HTTP Lifecycle: Reuses a shared httpx.AsyncClient, applies consistent timeouts, and closes it through the MCP server lifespan.
Bounded Authentication: MCP requests fail fast with actionable guidance when OAuth needs attention; browser authentication only runs when explicitly requested.
Output Safety: Domoticz responses are recursively sanitized before crossing the MCP boundary. Credential fields, OAuth transaction data, private endpoints, network addresses, and sensitive free-text patterns are redacted; high-risk configuration resources also use strict allowlists.
Type Safety: Full type annotations using Python 3.10+ union syntax for improved IDE support and code clarity.
Error Handling: Structured exception hierarchy (DomoticzError, DeviceNotFoundError, AuthenticationError, etc.) for precise error handling and debugging.
Shared Resolution: Unified _resolve_idx() helper function for consistent device/scene/variable lookup patterns.
Python 3.10 or higher
A running Domoticz instance
Network access to the Domoticz API
Clone or download this repository.
Navigate to the project directory.
Install the package using pip:
pip install .This will install the domoticz-mcp command-line tool.
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-mcpYou can run the server via Docker. By default, the Docker image runs the server in sse (HTTP) mode on port 8000.
docker run -d \
--name domoticz-mcp \
-p 8000:8000 \
-e DOMOTICZ_URL="http://192.168.1.100:8080" \
-e DOMOTICZ_USERNAME="your_username" \
-e DOMOTICZ_PASSWORD="your_password" \
ghcr.io/adrighem/domoticz-mcp:latestNote: For the OAuth2 token flow to work and persist in Docker without interactive browser prompts, see the OAuth / API Token section below on how to mount the token file or use headless authentication.
The server supports three different transports for clients to connect with:
stdio (Default): Standard input/output. This is what most desktop applications (like Claude Desktop and Gemini CLI) use.
domoticz-mcp --transport stdiosse (HTTP Server-Sent Events): Starts a web server that clients can connect to over HTTP. Ideal for web-based UIs and remote connections. Includes wide-open CORS headers.
domoticz-mcp --transport sse --port 8000Connection URL for clients: http://localhost:8000/sse
streamable-http (Alternative HTTP): Starts a web server using an alternative HTTP transport. Required by certain clients (like the llama.cpp WebUI) that expect a single POST endpoint instead of an SSE stream.
domoticz-mcp --transport streamable-http --port 8000Connection URL for clients: http://localhost:8000/mcp
The server can be configured via environment variables, a .env file, or command-line arguments. Environment variables take precedence over command-line arguments, which in turn override the defaults. Using a .env file is a convenient way to provide these variables without exposing them in your shell history.
Option | Environment Variable | Default | Description |
|
|
| Transport to use ( |
|
|
| Host to bind to for SSE / HTTP |
|
|
| Port to bind to for SSE / HTTP |
|
|
| Base URL of your Domoticz instance |
|
|
| Path to OAuth token storage file |
Example .env file:
DOMOTICZ_URL=http://192.168.1.100:8080
DOMOTICZ_CLIENT_ID=your_client_id_here
DOMOTICZ_CLIENT_SECRET=your_client_secret_hereBy default, the server uses standard input/output (stdio) for communication with the MCP client. You can also run it as an HTTP Server-Sent Events (SSE) streaming server using the --transport sse argument.
domoticz-mcp --transport sse --host 127.0.0.1 --port 8000You can authenticate the MCP server with Domoticz using either an OAuth/API Token (Recommended) or Basic Auth.
This approach uses an OAuth2 token and is generally more secure.
Option | Environment Variable | Description |
|
| Your Application's Client ID |
|
| Your Application's Client Secret |
|
| Direct OAuth2 access token (skips flow) |
In the Domoticz UI, go to Setup -> More Options -> Applications.
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.
Note the generated Client ID and Client Secret.
Interactive Flow (Desktop/CLI): Run the explicit authentication command in an interactive terminal:
domoticz-mcp --authenticateThe command opens a local browser and waits up to two minutes for the callback without printing the authorization or callback URL. After approval, it stores the token with owner-only file permissions and starts the MCP server. Normal MCP requests never launch a browser; if refresh fails, they return an actionable authentication error instead of waiting indefinitely.
Interactive Flow from Codex or another MCP client:
Call start_oauth_login.
Complete approval in the browser opened on the MCP host.
Call get_oauth_login_status with the returned flow_id until its status is complete.
Retry the original Domoticz operation.
The start tool bounds the local browser launch to five seconds and reuses an existing pending flow, so it does not wait for browser approval. The callback listener binds only to 127.0.0.1, expires after two minutes, validates OAuth state and PKCE, and never returns authorization URLs, tokens, or authorization codes through MCP.
This tool flow is intended for a local MCP server such as Codex STDIO. Remote containers and execution hosts should use the command-line authentication flow on a browser-capable host or a securely mounted token file.
Headless Flow (Docker / Server Environments): In a Docker container, you have two options:
Password Grant (Easiest): Provide username and password in addition to the Client ID and Secret. The server will automatically perform a headless login to fetch the initial token.
Mount Token File: Run the server locally once to generate the token file, then mount it into the container.
If you prefer traditional username and password authentication:
Option | Environment Variable | Description |
|
| Your Domoticz username |
|
| Your Domoticz password |
In the Domoticz UI, go to Setup -> Settings -> Security.
Ensure "Allow Basic-Auth authentication over plain HTTP" is enabled (if you are not using HTTPS).
Add the following to your ~/.gemini/settings.json under the mcpServers object:
{
"mcpServers": {
"domoticz": {
"command": "uv",
"args": [
"--directory",
"/path/to/domoticz-mcp",
"run",
"domoticz-mcp"
],
"env": {
"DOMOTICZ_URL": "http://192.168.1.x:8080",
"DOMOTICZ_CLIENT_ID": "your_client_id_here",
"DOMOTICZ_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"domoticz": {
"command": "uv",
"args": [
"--directory",
"/path/to/domoticz-mcp",
"run",
"domoticz-mcp"
],
"env": {
"DOMOTICZ_URL": "http://192.168.1.x:8080",
"DOMOTICZ_CLIENT_ID": "your_client_id_here",
"DOMOTICZ_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}If you installed it globally via pip, you can use the command directly:
{
"mcpServers": {
"domoticz": {
"command": "domoticz-mcp",
"args": [],
"env": {
"DOMOTICZ_URL": "http://192.168.1.x:8080",
"DOMOTICZ_CLIENT_ID": "your_client_id_here",
"DOMOTICZ_CLIENT_SECRET": "your_client_secret_here"
}
}
}
}For other clients that support the Model Context Protocol, simply configure them to run the domoticz-mcp binary or the uv run command with the appropriate environment variables.
To develop and run tests for this project:
Clone the repository.
Install development dependencies using uv:
uv pip install -e ".[dev]"Run the test suite:
uv run --extra dev pytest tests/Build the package locally:
uv run --extra dev python -m buildYou can also pass --directory /path/to/domoticz-mcp to either uv run command when running from outside the repository.
This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.
Add var. vtype: 0=Int, 1=Float, 2=Str, 3=Date, 4=Time. Cross-ref: domoticz://user-variables.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New user variable name | |
| value | Yes | Initial user variable value | |
| vtype | Yes | Variable type: 0 integer, 1 float, 2 string, 3 date, 4 time |
| Name | Required | Description |
|---|---|---|
| title | No | Optional Domoticz response title |
| status | Yes | Status returned by Domoticz, normally OK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses only the vtype mapping and a cross-reference. It does not mention side effects (e.g., duplicate handling), authorization needs, or any behavioral traits beyond the annotations, which are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two fragments), which is concise but lacks structure. It could be better organized as a proper sentence with clearer specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is too sparse. It fails to explain the operation's effect, expected return, or any special conditions. The cross-reference is not explained, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description redundantly restates the vtype enum mapping already present in the schema, adding no new semantic value for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Add user variable' and description 'Add var' clearly indicate the action, though the description is terse and could be more explicit. The sibling tools (update, delete) help disambiguate, making the purpose clear overall.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus update_user_variable or delete_user_variable. It only offers a vtype mapping, so an agent lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create script. Cross-ref: domoticz://docs/dzvents_syntax.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New event script name | |
| event_type | Yes | Domoticz event type | |
| eventstatus | No | 1 to enable the event, 0 to disable it | 1 |
| interpreter | Yes | Domoticz event interpreter | |
| xmlstatement | Yes | Event source or Blockly XML |
| Name | Required | Description |
|---|---|---|
| title | No | Optional Domoticz response title |
| status | Yes | Status returned by Domoticz, normally OK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructive, but the description adds no behavioral context beyond 'Create'. It does not explain side effects, required permissions, or interaction with the Domoticz system referenced in the cross-link.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While short, the description is overly terse (one sentence) given the tool has 5 parameters and a cross-reference. It sacrifices completeness for brevity, and the cross-reference may require external lookup.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fails to provide context for the 'xmlstatement' field, event types, or interpreter options. An output schema exists but its content is absent from the description. The cross-reference partially compensates but is not self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are documented individually. The tool description adds no extra semantic meaning; baseline 3 is appropriate as the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Create event script' and description 'Create script' indicate the purpose of creating an event or script, but lack specificity about what kind of event or what 'script' refers to. It is barely sufficient to distinguish from siblings like 'update_event', but does not clarify scope or output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'update_event' or 'delete_user_variable'). No prerequisites, contraindications, or contextual triggers are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete var. Preferred: idx. Requires confirm=True.
| Name | Required | Description | Default |
|---|---|---|---|
| idx | No | Numeric Domoticz idx; preferred over name when known | |
| name | No | Case-insensitive Domoticz entity name | |
| confirm | No | Explicitly confirm this high-impact operation |
| Name | Required | Description |
|---|---|---|
| title | No | Optional Domoticz response title |
| status | Yes | Status returned by Domoticz, normally OK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the important behavioral note that confirmation is required, which is useful beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at two short sentences with no wasted words. The key information (purpose, preference, requirement) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with an output schema available, the description is adequate but minimal. It lacks details on consequences beyond the confirmation requirement, but covers essential usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description reinforces the preference for idx and the requirement for confirm, but does not add new semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Delete var', which clearly indicates a delete operation on a user variable. The verb-resource pairing is specific and distinguishable from sibling tools like add_user_variable and update_user_variable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on parameter preference ('Preferred: idx') and a requirement ('Requires confirm=True'), but does not explicitly specify when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a browser login. Retry the original operation only after status is complete.
| Name | Required | Description | Default |
|---|---|---|---|
| flow_id | Yes | Opaque flow identifier returned by start_oauth_login |
| Name | Required | Description |
|---|---|---|
| status | Yes | Current login flow state |
| flow_id | Yes | Opaque login flow identifier |
| message | Yes | Current state and next action |
| expires_at | Yes | UTC time when the authorization window expires |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and open-world behavior. The description adds behavioral context by mentioning that the tool checks a browser login and that the agent should retry only after status completes, which guides correct invocation. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that state the purpose and provide essential guidance. Every word is necessary, with no fluff. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter) and rich annotations plus output schema, the description is nearly complete. It lacks explicit instruction to call repeatedly for polling, but this is implied by the retry guidance. Suitable for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of 'flow_id' as an opaque identifier from start_oauth_login. The tool description does not add additional parameter semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Check a browser login', which clearly indicates the tool's function of verifying OAuth login status. It distinguishes itself from sibling tools that manage devices, variables, and events. However, it could be more specific about what 'check' returns (e.g., status or progress).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implicit usage guidance: 'Retry the original operation only after status is complete.' This suggests polling behavior but does not explicitly state when to use the tool versus alternatives, nor does it provide exclusions. A more explicit usage context would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set brightness (0-100). Preferred: idx. Cross-ref: domoticz://device/{idx}.
| Name | Required | Description | Default |
|---|---|---|---|
| idx | No | Numeric Domoticz idx; preferred over name when known | |
| name | No | Case-insensitive Domoticz entity name | |
| level | Yes | Brightness percentage |
| Name | Required | Description |
|---|---|---|
| title | No | Optional Domoticz response title |
| status | Yes | Status returned by Domoticz, normally OK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent, destructive, and non-read-only behavior. The description adds no further behavioral details (e.g., side effects, authentication). It provides the brightness range, which is already in the schema. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The key purpose is front-loaded, followed by a usage hint. Every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple tool with good schema coverage, annotations, and output schema. It covers the core operation, parameter preferences, and cross-reference, requiring no further explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by stating 'Preferred: `idx`' and providing a cross-reference link, which helps the agent prioritize parameters beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set brightness') and specifies the valid range (0-100). It also distinguishes the preferred parameter (idx) from alternatives, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using 'idx' over 'name', which guides parameter selection. However, it does not specify when not to use the tool or mention alternatives (though sibling tools are unrelated, so no explicit exclusion is necessary).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update script. Cross-ref: domoticz://event/{event_id}. Requires confirm=True.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Event script name | |
| confirm | No | Explicitly confirm this high-impact operation | |
| event_id | Yes | Canonical Domoticz event ID | |
| event_type | Yes | Domoticz event type | |
| eventstatus | No | 1 to enable the event, 0 to disable it | 1 |
| interpreter | Yes | Domoticz event interpreter | |
| xmlstatement | Yes | Replacement event source or Blockly XML |
| Name | Required | Description |
|---|---|---|
| title | No | Optional Domoticz response title |
| status | Yes | Status returned by Domoticz, normally OK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's mention of 'Requires confirm=True' adds limited value by confirming the high-impact nature. No contradictions with annotations. Additional behavioral details about the update process are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences), which is concise but omits important context. It is front-loaded but lacks detail about the tool's purpose and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters (5 required) and an output schema not described, the description is incomplete. It does not explain return values, side effects, or differentiation from sibling 'create_event'. The tool is complex but the description is sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema already documents all parameters. The description does not add any extra semantic meaning beyond what is in the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update script' which clearly indicates a modification operation on an event script, and the cross-reference provides context. However, it does not distinguish itself from the sibling tool 'create_event' or specify the scope of update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'create_event'. The description mentions a requirement for confirm=True but does not explain when this tool is appropriate or when other tools should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update var value. Cross-ref: domoticz://user-variables.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Existing user variable name | |
| value | Yes | New user variable value | |
| vtype | Yes | Variable type: 0 integer, 1 float, 2 string, 3 date, 4 time |
| Name | Required | Description |
|---|---|---|
| title | No | Optional Domoticz response title |
| status | Yes | Status returned by Domoticz, normally OK |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, which description does not elaborate on. No added behavioral context beyond cross-reference.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and to the point. No wasted words, but could include more information without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing usage guidelines and behavioral details. Output schema exists, so return values are covered. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update var value' with the resource being user variables. Title matches. Distinguishes from siblings: add and delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives (e.g., when to update vs add). The cross-reference is not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a distinct purpose: login status, dimmer control, user variable CRUD, and event management. No two tools overlap in functionality.
All tools follow a consistent verb_noun pattern using snake_case, e.g., get_oauth_login_status, set_dimmer_level, add_user_variable. Verbs appropriately describe actions.
With 7 tools, the set is well-scoped for a focused integration covering authentication, device control, variables, and events. Not overly large or small.
Missing essential operations: no get_user_variable to read variables, no delete_event, and no tools for other common Domoticz devices like switches or sensors. Gaps may cause agent failures.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/adrighem/domoticz-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
