Domotz

Domotz MCP 服务

用于 Domotz 网络监控和管理的模型上下文协议（MCP）服务。可让 AI 助手监控网络设备、查看警报、检查设备状态并管理网络基础设施。

这是一个 模型上下文协议（MCP） 服务，可将 Claude（或任何兼容 MCP 的 AI）连接到你的 Domotz 环境。

属于 MSP Claude Plugins 生态系统的一部分 — 这是一个不断扩展的 MSP 技术栈 AI 集成套件。由 MSP 为 MSP 构建。

安装

npm install @wyre-ai/domotz-mcp

配置

复制 .env.example，并设置以下变量。

变量	必填	说明
DOMOTZ_API_KEY	用于 stdio 和 AUTH_MODE=env	Domotz Public API 密钥
DOMOTZ_REGION	否	API 区域单元标签（默认值：us-east-1）
MCP_TRANSPORT	否	stdio（默认值）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。Gateway 模式要求每个 /mcp 请求都携带 X-Domotz-API-Key，且绝不会回退使用 DOMOTZ_API_KEY。env 仅在 S2S 身份验证成功后使用该变量。
CONDUIT_S2S_SECRET	HTTP 必填	服务到服务密钥。如果该值为空或为已知占位值（changeme、secret、your-s2s-secret、replace-with-a-real-secret 以及 src/http.ts 中拒绝的其他值），HTTP 服务会记录错误并以非零状态退出。未设置该值时，Compose 不会启动。切勿提交真实密钥。该值绝不会被记录到日志中。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时，设置为 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，且仅绑定到 127.0.0.1。非环回地址的 MCP_HTTP_HOST 会被忽略，并记录该覆盖操作。已知占位密钥仍会被拒绝。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。默认值为 127.0.0.1。设置 CONDUIT_S2S_SECRET 后才会采用该值。容器镜像将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认值为 8080。

/health 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。验证逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：标头值的格式为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的差值必须在 300 秒以内。缺少标头或标头无效时，会在读取供应商凭据前返回 401。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Domotz-API-Key: $DOMOTZ_API_KEY" \
  -H 'X-Domotz-Region: us-east-1' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Domotz-API-Key（X-Domotz-Region 为可选项，默认值为 us-east-1）。该标头是此请求唯一的凭据来源。在 AUTH_MODE=env 模式下，仍必须提供有效的 X-Gateway-S2S 标头，供应商凭据则来自 DOMOTZ_API_KEY。

使用方法

与 Claude Desktop 搭配运行

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "domotz-mcp": {
      "command": "npx",
      "args": ["@wyre-ai/domotz-mcp"],
      "env": {
        "DOMOTZ_API_KEY": "your-domotz-api-key"
      }
    }
  }
}

与 Claude Code（CLI）搭配运行

claude mcp add domotz-mcp \
  -e DOMOTZ_API_KEY=your-value \
  -- npx -y @wyre-ai/domotz-mcp

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到回环地址，并传入 S2S 密钥。在网关模式下，Domotz API 密钥会随每个请求通过 X-Domotz-API-Key 传入；不会从环境变量中读取。Compose 不会设置 DOMOTZ_API_KEY。

docker build -t domotz-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  domotz-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，并发布 127.0.0.1:8080:8080。使用 openssl rand -hex 32 生成密钥；不要使用 your-s2s-secret 之类的占位符。

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需 S2S 密钥，然后使用 DOMOTZ_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e DOMOTZ_API_KEY=your-value \
  -e DOMOTZ_REGION=us-east-1 \
  -p 127.0.0.1:8080:8080 \
  domotz-mcp

不带密钥的本地 HTTP 仅用于开发环境。它只绑定到 127.0.0.1，并会记录一条警告。非回环地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

可用领域

Agent

管理 Domotz 监控 Agent

警报

查看和管理网络警报

设备

设备发现和状态监控

指标

网络性能指标

网络

网络拓扑和配置

电源

管理设备的电源

开发

# Clone the repository
git clone https://github.com/WYRE-AI/domotz-mcp.git
cd domotz-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# HTTP transport refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

贡献

欢迎贡献！如果存在 CONTRIBUTING.md，请参阅该文件；也可以提交 issue 讨论更改。

许可证

本项目根据 Apache License 2.0 版授权。详情请参阅 LICENSE。