Skip to main content
Glama
Sign In
mahdsip

home-mcp

by mahdsip
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

home-mcp

Home MCP server for the familIA voice assistant. One process, four optional modules; each is enabled only when its settings are present.

The Python package and the installed command are still named familia-mcp (familia_mcp): the deployed host (/opt/familia-mcp, the familia-mcp service user) and the familIA proxy's forced SSH command rely on that name.

Module

Tools

Access

Prometheus

prom_devices_overview, prom_device_status, prom_metric_history, prom_active_alerts

read-only

Home Assistant

ha_list_devices, ha_device_state, ha_device_history, ha_control

lights and plugs in an allowlist

Plex

plex_search, plex_recently_added, plex_continue_watching, plex_watch_history, plex_now_playing

read-only

Photos (PhotoPrism)

photos_search, photos_albums, photos_people, photos_on_this_day

read-only

How it runs

The server speaks MCP over stdio. It is not a network service: the familIA proxy starts it through SSH with a restricted key whose forced command is the server (restrict,command="/opt/familia-mcp/venv/bin/familia-mcp"). Nothing listens on the LAN.

voice (OVOS) -> familIA proxy -- SSH, forced command --> familia-mcp (this repo) -> Prometheus / HA / Plex / PhotoPrism

The tool calls themselves come from the familIA Lambda as "return of control": the model never reaches the home services directly; the proxy runs the tool here and sends back the result.

Related MCP server: HomeLab MCP

Safety model

  • Home Assistant: only light and switch domains exist in the module. /etc/familia/ha_allowlist.json decides which entities are visible and which actions each may take (missing or invalid file -> nothing exposed). Devices with "confirm": true are only parked: the proxy asks the user and runs the internal ha_confirm_action tool itself after a spoken "yes"; that tool is never declared to the model. See deploy/ha_allowlist.example.json.

  • Plex: the owner token can do anything on the server, so the client only issues GET requests to a fixed list of paths. "Continue watching" for Plex Home users uses each user's own token and never falls back to the owner's.

  • Photos: a thin client of PhotoPrism's built-in read-only MCP endpoint (/api/v1/mcp). Use an app password with scope mcp read photos albums people labels; without places no coordinates are ever returned.

  • Tokens live only in /etc/familia/mcp.env on the MCP host (mode 600, owned by the service user).

Install / upgrade (Raspberry Pi OS, Python 3.11+)

On a dev machine:

uv run pytest -q
uv build --wheel
scp dist/familia_mcp-*.whl requirements.lock.txt deploy/install.sh deploy/mcp.env.example <mcp-host>:/tmp/familia-mcp/
# optional: your allowlist and a secrets.env (KEY=VALUE, merged into mcp.env and then deleted)

On the MCP host:

sudo bash /tmp/familia-mcp/install.sh

install.sh is idempotent: service user, venv with hash-verified dependencies (requirements.lock.txt), config files that are never overwritten except by an explicit ha_allowlist.json / secrets.env next to it, and a final check that calls one read tool per enabled module. Then authorize the proxy's key with deploy/authorize_proxy_key.sh and restart the proxy so it re-reads the tool list.

Helpers: deploy/ha_token.sh (store the HA token without echoing it), deploy/ha_notify_services.sh (list HA notify services).

Configuration

All settings are KEY=VALUE lines in /etc/familia/mcp.env (override the path with FAMILIA_MCP_ENV_FILE); see deploy/mcp.env.example.

Module

Required

Optional

Prometheus

PROMETHEUS_URL

PROMETHEUS_DEVICE_LABEL, PROMETHEUS_TIMEOUT_S, bearer / basic auth

Home Assistant

HA_URL, HA_TOKEN

HA_ALLOWLIST_FILE, HA_TIMEOUT_S

Plex

PLEX_URL, PLEX_TOKEN

PLEX_USER_TOKENS=Kids=<token>;..., PLEX_TIMEOUT_S

Photos

PHOTOPRISM_URL, PHOTOPRISM_TOKEN

PHOTOPRISM_TIMEOUT_S

Development

uv sync
uv run pytest -q          # fake HTTP backends and an in-process fake PhotoPrism MCP server

mcp is pinned (mcp==2.3.0): the 2.x API differs from 1.x, and the familIA proxy must use the same version. Tool descriptions are in English; the assistant answers in the user's language.

License

GPL-3.0-only. See LICENSE.

Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • ha-mcp

    qubit999
    A
    license
    A
    quality
    C
    maintenance
    A self-hosted MCP server for Home Assistant that exposes full control over entity states, service calls, history, templates, and areas via local stdio, enabling AI assistants to manage your smart home.
    9
    122 npm
    MIT

  • HomeLab MCP

    chip10
    F
    license
    C
    quality
    D
    maintenance
    MCP server that integrates Home Assistant, Frigate, Docker, and Proxmox via STDIO, enabling secure read and write operations with configurable confirmation.
    26
    -

  • homelab-mcp

    breixopd
    A
    license
    Not graded
    quality
    B
    maintenance
    Read-only MCP adapter for Homelab Core that lets AI assistants inspect health, services, redacted logs, nodes, and jobs via a local Unix socket. Optionally enables job queuing when changes are explicitly allowed.
    MIT

  • mcp-ha

    Devitek
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server for Home Assistant that lets you control and query your smart home through natural language via MCP clients. Provides tools for entities, devices, services, automations, scripts, history, add-ons, and system info, with read-only access by default and optional configurable write support.
    1
    MIT