smarthome-port

smarthome-port

smarthome-port talks to a Home Assistant instance through its REST API. Everything in Home Assistant is an entity — light.kitchen, sensor.temp, switch.porch — and the API reflects that shape: you read entity states, call services on a domain (light.turn_on, switch.toggle), look back at recent history, read the core configuration, render Jinja templates on the server, and fire events onto the event bus. smarthome-port exposes those six operations, plus listings of entities and services, through one binary that serves a command-line interface and a stdio MCP server.

Two settings are required, and there is no built-in default for either:

• HOME_ASSISTANT_URL — the base URL of the instance, for example http://homeassistant.local:8123. A trailing slash is stripped.
• HOME_ASSISTANT_TOKEN — a long-lived access token (create one in Home Assistant under your profile). It is sent as an Authorization: Bearer header and never appears in output.

When either variable is missing, every call fails with an error that names the missing variable, before any request is made.

Only the REST API is covered. The websocket API is not implemented.

Install

npx @reneturcios/smarthome-port entities

Or run the container image:

docker run -i -e HOME_ASSISTANT_URL -e HOME_ASSISTANT_TOKEN ghcr.io/cloudcorprecords/smarthome-port

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

export HOME_ASSISTANT_URL=http://homeassistant.local:8123
export HOME_ASSISTANT_TOKEN=<your long-lived access token>

smarthome-port entities
smarthome-port entities --domain light
smarthome-port state sensor.temp
smarthome-port call light turn_on --entity light.kitchen --data '{"brightness_pct":50}'
smarthome-port services
smarthome-port services --domain light
smarthome-port history sensor.temp --hours 6
smarthome-port config
smarthome-port render "{{ states('sensor.temp') }}"
smarthome-port fire my_event --data '{"device":"kitchen"}'

smarthome-port --version

Each command prints the upstream JSON payload (template rendering prints {"rendered": "..."}). Exit codes: 0 on success, 1 when a call fails (including missing configuration or an API error), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/smarthome-port mcp

MCP client configuration:

{
  "mcpServers": {
    "smarthome-port": {
      "command": "npx",
      "args": ["-y", "@reneturcios/smarthome-port", "mcp"],
      "env": {
        "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
        "HOME_ASSISTANT_TOKEN": "..."
      }
    }
  }
}

Tools

Tool	Input	What it returns
list_entities	domain (optional)	Entity states, filtered client-side to one domain when given.
get_entity_state	entity_id (required)	The full state of one entity.
call_service	domain, service (required), entity_id, service_data (optional)	The service call result; service_data is merged with entity_id.
list_services	domain (optional)	Services by domain, or only one domain's entry when given.
get_history	entity_id (required), hours (optional, default 24)	Recent history for the entity over the window ending now.
get_config	(none)	The core configuration.
render_template	template (required)	{"rendered": "..."} — the upstream reply is plain text.
fire_event	event_type (required), event_data (optional)	The upstream reply; event_data defaults to {}.

All calls go to {HOME_ASSISTANT_URL}/api. An entity_id must contain a dot (domain.object_id), and domain, service, and event_type must be non-empty — both are checked before any request. History timestamps are computed client-side from the current time. HTTP failures surface the status plus the upstream message when Home Assistant provides one.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.