AI导哈

智能家居设备交互服务器

Homie MCP Server 是一个让LLM通过MQTT与Homie 5智能家居设备交互的服务器，它抽象了MQTT主题和Homie约定，提供了一个干净的设备导向API。

  • by Tieske
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Tieske/homie5-mcp-server

使用说明

Homie MCP Server

An MCP server that lets LLMs interact with Homie 5 smart home devices over MQTT. It abstracts away MQTT topics and the Homie convention, presenting a clean device-oriented API.

How it works

  1. On startup (or after homie_connect), subscribes to {domain}/5/+/$state and {domain}/5/+/$description
  2. When a device's $description arrives (retained JSON), parses it and subscribes to {domain}/5/{deviceId}/+/+ for all property values
  3. Property values are cached as they arrive — the cache is always up to date
  4. When a device's $state is cleared (empty payload), the device is removed from the cache
  5. Tool calls read from the cache (instant) or publish set commands to MQTT

Setup

npm install
npm run build

Configuration

Configuration is via environment variables. There are two modes:

Pre-configured mode: Set HOMIE_BROKER_URL and the server connects on startup. The homie_connect tool is not exposed.

Interactive mode: Omit HOMIE_BROKER_URL and the LLM connects via the homie_connect tool.

Credentials are included in the broker URL (e.g. mqtt://user:pass@broker:1883).

Variable Description Required Default
HOMIE_BROKER_URL MQTT broker URL (e.g. mqtt://user:pass@host:1883) No —
HOMIE_CLIENT_ID MQTT client ID No homie-mcp-{random}
HOMIE_DOMAIN Homie topic domain prefix No homie
HOMIE_SSE_PORT If set, run SSE transport on this port instead of stdio No —
HOMIE_TLS_CERT Path to PEM certificate file for HTTPS No —
HOMIE_TLS_KEY Path to PEM private key file for HTTPS No —

When using SSE transport, the server always runs over HTTPS. If both HOMIE_TLS_CERT and HOMIE_TLS_KEY are set, those certificates are used. If neither is set, a self-signed certificate is generated automatically. Setting only one of the two is an error.

Usage

Claude Code (pre-configured)

claude mcp add homie-mcp -- env HOMIE_BROKER_URL=mqtt://localhost:1883 node /path/to/homie-mcp-server/build/index.js

Claude Code (interactive)

claude mcp add homie-mcp -- node /path/to/homie-mcp-server/build/index.js

The LLM will need to call homie_connect before it can interact with devices.

Standalone (stdio)

HOMIE_BROKER_URL=mqtt://localhost:1883 node build/index.js

SSE transport (self-signed cert)

HOMIE_BROKER_URL=mqtt://localhost:1883 HOMIE_SSE_PORT=3000 node build/index.js

SSE transport (custom certs)

HOMIE_BROKER_URL=mqtt://localhost:1883 HOMIE_SSE_PORT=3000 HOMIE_TLS_CERT=cert.pem HOMIE_TLS_KEY=key.pem node build/index.js

Connect to https://localhost:3000/sse for the SSE stream, POST to /messages for requests.

Docker

docker build -t homie-mcp-server .
docker run --init -e HOMIE_BROKER_URL=mqtt://user:pass@broker:1883 homie-mcp-server

HOMIE_BROKER_URL is required — the container will refuse to start without it.

To use SSE transport:

docker run --init -e HOMIE_BROKER_URL=mqtt://broker:1883 -e HOMIE_SSE_PORT=3000 -p 3000:3000 homie-mcp-server

With custom certificates, mount them into the container:

docker run --init \
  -e HOMIE_BROKER_URL=mqtt://broker:1883 \
  -e HOMIE_SSE_PORT=3000 \
  -e HOMIE_TLS_CERT=/certs/cert.pem \
  -e HOMIE_TLS_KEY=/certs/key.pem \
  -v /path/to/certs:/certs:ro \
  -p 3000:3000 homie-mcp-server

Tools

homie_connect

Only available when HOMIE_BROKER_URL is not set.

Connect to an MQTT broker. If already connected, disconnects first and reconnects to the new broker. Automatically starts device discovery after connecting.

Param Type Required
broker_url string yes

Credentials go in the URL: mqtt://user:pass@host:1883.

homie_get_devices

List all discovered devices. Returns device ID, name, type, and state.

By default only returns active devices (state ready or sleeping). Pass include_all: true to also include devices in init, disconnected, and lost states.

homie_get_device

Get full details for a single device: state, description, all nodes and properties with their current values.

Param Type Required
device_id string yes

homie_get_value

Get the current value of a specific property, plus its metadata (datatype, unit, format, settable).

Param Type Required
device_id string yes
node_id string yes
property_id string yes

homie_set_value

Send a command to a settable property. The value is validated against the property's datatype and format before publishing.

Param Type Required
device_id string yes
node_id string yes
property_id string yes
value string yes

Validation rules:

  • boolean: must be "true" or "false"
  • integer: must be a whole number, checked against min:max range from format
  • float: must be a number, checked against min:max range from format
  • enum: must be one of the comma-separated values in format
  • color: validated against rgb or hsv format
  • datetime: must be valid ISO 8601
  • duration: must be ISO 8601 duration (e.g. PT30S)

The command is published to {topic}/set with QoS 0, non-retained, per the Homie spec.

homie_discover

Force re-discovery. Clears the device store, unsubscribes from everything, and resubscribes to discovery topics. Retained messages will repopulate the store. No parameters.

相关 MCP