io.github.CloudCorpRecords/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

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.