Domoticz MCP Server

Domoticz MCP服务器

](https://pypi.org/project/domoticz-mcp/) ](https://github.com/adrighem/domoticz-mcp/pkgs/container/domoticz-mcp) 

一种用于集成的模型上下文协议（MCP）服务器 多莫茨 家庭自动化系统。该服务器为AI助手（如Claude、Gemini等）提供工具，以查看和控制您的智能家居设备、场景、用户变量等。

特性

服务器暴露 工具 （用于主动控制和修改）， 资源 （用于只读上下文感知），以及 提示 （用于引导式交互模板）。

工具（动作）

• 搜索和发现： 使用 get_overview 用于高级系统摘要和设备计数。使用 search_devices 使用子字符串或正则表达式匹配按名称或当前状态查找设备。
• 维护： 主动识别需要注意的传感器 get_battery_levels （低电量警报）和 get_connectivity_report （尚未登记的设备）。使用 get_system_health 有关硬件网关状态的概述。检查系统更新 check_for_updates 并执行系统重启 restart_system.
• 能源分析： 使用 analyze_energy_usage 总结所有电力报告设备和仪表的每日消耗量。
• 设备控制： 切换开关、设置状态（开/关）、设置调光器级别（0-100）、设置恒温器温度（摄氏度）、控制百叶窗和管理RGB/彩色照明（亮度、色调、色温）。支持按以下方式查找 idx 或 name.
• 设备管理： 创建虚拟传感器、重命名设备、删除/隐藏设备以及手动更新传感器值。支持按以下方式查找 idx 或 name.
• 房间和场景： 控制场景/组。通过以下方式获取房间设备 idx 或 room_name.
• 用户变量： 读取、添加、更新和删除Domoticz用户变量。支持按以下方式查找 idx 或 name.
• 历史和日志： 通过以下方式访问设备历史图和文本/光日志 idx 或 name.检索系统日志并添加自定义日志消息。
• 系统信息： 获取Domoticz实例版本、全局设置、硬件、日照时间、用户和内部事件脚本/规则。
• 安全： 获取并设置Domoticz安全面板状态。
• 通知： 通过Domoticz通知子系统发送通知。
• 活动管理： 获取、创建、更新和 书内搜索 内部事件脚本(search_scripts).支持Blockly、Lua、dzVents和Python。
• 摄像头和平面图： 检索摄像头配置和定义的平面图。使用以下命令获取base64编码的快照 get_camera_snapshot.
• 高级： 使用 call_domoticz_api 以直接执行任何通用Domoticz API端点。

资源（上下文）

• domoticz://dashboard：阅读收藏和当前活动设备的精选视图（灯亮，传感器活动）。
• domoticz://devices：读取所有Domoticz设备的当前状态。
• domoticz://device/{idx}, domoticz://device/{type}/{subtype}/{idx}，或 domoticz://device/name/{name}：读取特定设备的当前状态。
• domoticz://rooms：阅读配置的房间（房间平面图）。
• domoticz://room/{idx} 或 domoticz://room/{room_name}/{idx}：读取特定房间内所有设备的完整状态。
• domoticz://scenes：读取配置的场景。
• domoticz://scene/{idx} 或 domoticz://scene/name/{name}：阅读属于特定场景的设备列表。
• domoticz://user-variables：读取所有Domoticz用户变量的列表。
• domoticz://user-variable/{idx} 或 domoticz://user-variable/name/{name}：读取特定的Domoticz用户变量。
• domoticz://events & domoticz://event/{event_id}：阅读事件脚本的概述和具体源代码。
• domoticz://log：读取当前Domoticz系统日志。
• domoticz://logs/error：从日志中读取仅包含“错误”级别条目的筛选视图。
• domoticz://security：读取安全面板的当前状态。
• domoticz://settings：读取全局Domoticz设置和配置。
• domoticz://hardware：读取配置的硬件网关。
• domoticz://docs/dzvents_syntax：编写dzVents自动化脚本的备忘单。
• domoticz://docs/blockly_syntax：Blockly XML自动化的语法规则。

提示（模板）

• agent_guidance：为AI代理提供有关Domoticz特定逻辑和最佳实践的关键知识。
• summarize_home：指示人工智能使用仪表板资源提供房屋当前状态的人类可读摘要。
• maintenance_report：全面的健康检查，审核电池、检查设备连接并检查系统日志中的错误。
• audit_batteries：专门审计所有传感器的电池电量，以找出低于特定阈值的电池电量。
• energy_audit：分析整个家庭的能源使用情况，以确定当今最大的消费者。
• find_devices_by_state：帮助查找处于特定状态的所有设备（例如，“显示所有打开的设备”）。
• troubleshoot_device：一个要求设备的模板 idx 或 name 并指示AI读取设备状态和系统日志以诊断问题。
• analyze_automations：指示AI检查您的内部事件脚本是否存在逻辑缺陷或优化。
• write_dzvents_script：通过提供语法规则和设备查找指令帮助AI编写dzVents脚本。
• write_blockly_script：帮助AI使用适当的XML表示构建Blockly自动化。
• system_update_check：指导AI检查系统更新并验证硬件网关健康状况。
• dashboard_organization：提示AI分析喜爱的设备并建议基于房间的分组。

性能和效率

• 缓存： 服务器为设备、场景、用户变量和房间实现了5分钟的TTL缓存，以显著降低API延迟和Domoticz负载。
• 连接池： 使用持久 httpx.AsyncClient 通过适当的生命周期管理，在长时间运行的会话中提高效率。服务器暴露 close_global_client() 用于清洁关机。

建筑

• 类型安全： 使用Python 3.10+联合语法的完整类型注释，以提高IDE支持和代码清晰度。
• 错误处理： 结构化异常层次结构(DomoticzError, DeviceNotFoundError, AuthenticationError用于精确的错误处理和调试。
• 共享解决方案： 统一 _resolve_idx() 用于一致设备/场景/变量查找模式的辅助函数。

先决条件

• Python 3.10或更高版本
• 正在运行的Domoticz实例
• 对Domoticz API的网络访问

安装

标准Python安装（Linux、macOS、Windows）

1. 克隆或下载此存储库。
2. 导航到项目目录。
3. 使用安装软件包 pip:

pip install .

这将安装 domoticz-mcp 命令行工具。

使用 uv （推荐）

如果你使用 uv，您可以直接从源代码存储库运行服务器，而无需全局安装：

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

Docker安装

您可以通过Docker运行服务器。默认情况下，Docker镜像运行服务器 sse 端口8000上的（HTTP）模式。

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/YOUR_GITHUB_USERNAME/domoticz-mcp:latest

*注意：为了使OAuth2令牌流在Docker中工作并在没有交互式浏览器提示的情况下持久存在，请参阅下面关于如何装载令牌文件或使用无头身份验证的OAuth/API令牌部分。*

交通方式

服务器支持三种不同的传输方式供客户端连接：

1. stdio （默认）： 标准输入/输出。这是大多数桌面应用程序（如Claude desktop和Gemini CLI）使用的。

   domoticz-mcp --transport stdio

1. sse （HTTP服务器发送事件）： 启动客户端可以通过HTTP连接的web服务器。非常适合基于web的UI和远程连接。包括完全打开的CORS标头。

   domoticz-mcp --transport sse --port 8000

客户端的连接URL： http://localhost:8000/sse

1. streamable-http （替代HTTP）： 使用替代HTTP传输启动web服务器。某些客户端（如llama.cpp WebUI）要求使用单个POST端点而不是SSE流。

   domoticz-mcp --transport streamable-http --port 8000

客户端的连接URL： http://localhost:8000/mcp

配置

服务器可以通过环境变量进行配置 .env 文件或命令行参数。 环境变量优先于命令行参数，这反过来会覆盖默认值。使用一个 .env file是一种方便的方式来提供这些变量，而无需在shell历史中公开它们。

常规选项

示例 .env 文件：

DOMOTICZ_URL=http://192.168.1.100:8080
DOMOTICZ_CLIENT_ID=your_client_id_here
DOMOTICZ_CLIENT_SECRET=your_client_secret_here

交通方式

默认情况下，服务器使用标准输入/输出(stdio)用于与MCP客户端通信。您还可以使用以下命令将其作为HTTP服务器发送事件（SSE）流服务器运行 --transport sse 争论。

domoticz-mcp --transport sse --host 127.0.0.1 --port 8000

身份验证选项

您可以使用以下任一方式使用Domoticz对MCP服务器进行身份验证 OAuth/API令牌 （推荐）或 基本认证.

选项1:OAuth/API令牌（推荐）

这种方法使用OAuth2令牌，通常更安全。

1. 在Domoticz UI中，转到 设置 -> 更多选项 -> 应用程序.
2. 点击 添加应用程序 并配置：

- 名称例如。， MCP Server - 公开：如果要使用密钥对，请选中此项，或者对共享密钥不选中此项。

1. 注意生成的 客户端ID 和 客户端密钥.

交互式流（桌面/CLI）： 当服务器首次在您的计算机上本地运行时，它将打印一个到控制台/stderr的授权URL，并尝试打开您的浏览器。批准请求后，它将把令牌保存到 token-file 以备将来使用。

无头流（Docker/服务器环境）： 在Docker容器中，你有两个选择：

1. 密码授予（最简单）： 提供用户名和密码 *除了* 客户端ID和密码。服务器将自动执行无头登录以获取初始令牌。
2. 装载令牌文件： 在本地运行服务器一次以生成令牌文件，然后将其装载到容器中。

选项2：基本身份验证

如果您更喜欢传统的用户名和密码身份验证：

1. 在Domoticz UI中，转到 设置 -> 设置 -> 安全.
2. 确保启用了“允许通过纯HTTP进行基本身份验证”（如果您没有使用HTTPS）。

MCP客户端配置

Gemini CLI

将以下内容添加到您的 ~/.gemini/settings.json 在...之下 mcpServers 对象：

{
  "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"
      }
    }
  }
}

克劳德桌面版

将以下内容添加到您的 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"
      }
    }
  }
}

如果你通过pip全局安装它，你可以直接使用命令：

{
  "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"
      }
    }
  }
}

其他MCP客户端

对于支持模型上下文协议的其他客户端，只需将其配置为运行 domoticz-mcp 二进制或 uv run 使用适当的环境变量执行命令。

开发和测试

要为此项目开发和运行测试，请执行以下操作：

1. 克隆存储库。

1. 使用安装开发依赖项 uv:

   uv pip install -e ".[dev]"

1. 运行测试套件：

   uv run pytest tests/

或使用 uv run 直接无需安装：

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

许可证

本项目根据GNU通用公共许可证v3.0（GPLv3）获得许可。看 许可证 文件以获取详细信息。