convez.ai
MCP ServerAutomaçãoAvançado
electrification-bus

Homie 5 MCP Server

electrification-bus/homie5-mcp-server

Interface MQTT para controlar dispositivos Homie 5 via Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta LLMs a dispositivos de casa inteligente Homie 5 via MQTT. Abstrai a complexidade dos tópicos MQTT e da convenção Homie, oferecendo uma API orientada a dispositivos limpa e intuitiva. Suporta descoberta automática, cache de propriedades e controle em tempo real.

Instalação

$npx convez-ai electrification-bus/homie5-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automação de casa inteligente com LLM
  • Integração de sensores e atuadores Homie em assistentes de IA
  • Controle remoto de dispositivos MQTT através de linguagem natural

Veredito

MCP server bem estruturado para quem já usa Homie 5 e quer integrar controle via Claude. Requer conhecimento de MQTT, Homie convention e deployment — não é plug-and-play para iniciantes, mas oferece suporte sólido a modo pré-configurado e interativo.

README

A tradução para o português deste README ainda está na fila.

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).

VariableDescriptionRequiredDefault
HOMIE_BROKER_URLMQTT broker URL (e.g. mqtt://user:pass@host:1883)No—
HOMIE_CLIENT_IDMQTT client IDNohomie-mcp-{random}
HOMIE_DOMAINHomie topic domain prefixNohomie
HOMIE_SSE_PORTIf set, run SSE transport on this port instead of stdioNo—
HOMIE_TLS_CERTPath to PEM certificate file for HTTPSNo—
HOMIE_TLS_KEYPath to PEM private key file for HTTPSNo—

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.

ParamTypeRequired
broker_urlstringyes

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.

ParamTypeRequired
device_idstringyes

homie_get_value

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

ParamTypeRequired
device_idstringyes
node_idstringyes
property_idstringyes

homie_set_value

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

ParamTypeRequired
device_idstringyes
node_idstringyes
property_idstringyes
valuestringyes

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.

Ver o original no GitHub

Bom para

Relacionados