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 sta