hass-mcp

library0.1.7jsnpmunverified

An open-source MCP server (v0.1.7) for controlling and querying Home Assistant via REST API and WebSocket. It exposes three tool calls: ha_get_state, ha_list_states, and ha_call_service. Communicates over stdin/stdout (stdio transport) and requires Home Assistant long-lived access tokens. Unlike the official Home Assistant MCP server (which may have different tool names or features), hass-mcp is community-maintained and lightweight. It ships TypeScript types and requires Node >=24. Notable: it is a thin wrapper around Home Assistant's REST API; no direct WebSocket control. Prefer running on the same LAN as Home Assistant for security.

devops

npm install hass-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HASS-MCP

hass-mcp

devopsjavascriptv0.1.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

main

✓ import { main } from 'hass-mcp'

✗ import hassMCP from 'hass-mcp'

The package exports a main function, not a default export.

HASS_URL, HASS_TOKEN

✓ process.env.HASS_URL ?? ''

✗ import { HASS_URL } from 'hass-mcp'

Configuration is via environment variables, not exported constants.

ha_get_state, ha_list_states, ha_call_service

✓ // Tools are exposed by the server, not imported directly. They are called by the MCP client.

These are tool names provided by the server, not exported symbols.

Initializes and runs hass-mcp programmatically with Home Assistant URL and long-lived access token.

import { main } from 'hass-mcp'; // Ensure environment variables are set const url = process.env.HASS_URL ?? 'http://homeassistant.local:8123'; const token = process.env.HASS_TOKEN ?? ''; if (!url || !token) { console.error('HASS_URL and HASS_TOKEN environment variables are required'); process.exit(1); } // Run the MCP server (stdio transport) main({ hassUrl: url, hassToken: token }).catch(err => { console.error('MCP server error:', err); process.exit(1); });

Debug

Known issues

gotchaThe server does not support WebSocket events or real-time updates; it only provides tool calls that query or act via REST API.

fix

If you need real-time updates, consider using Home Assistant WebSocket API directly or another MCP server that supports subscriptions.

affects: >=0.1.0

gotchaThe server is designed to run on the same LAN as Home Assistant; exposing it over the internet without additional security (e.g., Cloudflare Access) may leak tokens or control capabilities.

fix

Run the server on the same LAN or behind a secure reverse proxy like Cloudflare Access.

affects: >=0.1.0

gotchaha_list_states can return a large payload; it may be slow or exceed memory limits if your Home Assistant has many entities.

fix

Use ha_get_state to query specific entities instead of listing all states.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'hass-mcp'

Package not installed or not in node_modules.

fix

Run npm install hass-mcp or pnpm add hass-mcp (requires Node >=24).

Error: HASS_TOKEN environment variable is not set

Missing required environment variable for authentication.

fix

Set HASS_TOKEN to a valid long-lived access token from Home Assistant.

Error: Invalid URL: ...

HASS_URL is not a valid URL or not reachable.

fix

Ensure HASS_URL includes protocol and port, e.g., http://homeassistant.local:8123.

Upgrade

Version history

0.1.7latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredCore MCP server SDK for tool registration and JSON-RPC protocol handling

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/hannoeru/hass-mcp ↗

packagehass-mcp ↗

homepagehttps://github.com/hannoeru/hass-mcp#readme ↗