Skip to main content
Glama
max-rousseau

MCP-HASS

by max-rousseau
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP-HASS

Version Python MCP SDK

MCP-HASS connects AI assistants to Home Assistant through the Model Context Protocol (MCP). It exposes Home Assistant entities, services, areas, devices, and cameras as MCP tools that any compatible AI client can use to monitor and control a smart home.

Features

  • 10 MCP tools covering entity discovery, service calls, area/device management, camera snapshots, and YAML config reload

  • Dual-API client: REST for entity states and service calls, WebSocket for area/device/entity registries

  • Self-healing connections with automatic reconnection and retry logic

  • Token-aware responses with configurable limits to avoid exceeding LLM context windows

  • Two deployment modes: stdio (Claude Desktop) and HTTP (Docker, any MCP client)

  • TLS certificate verification toggle for self-signed cert deployments (HA_SSL_VERIFY)

  • Launch script with MCP Inspector smoke tests for end-to-end validation

Related MCP server: Home Assistant MCP

Architecture

Modular dependency-injection architecture built on FastMCP. The server is a thin orchestrator that delegates to focused tool modules via ToolContext.

graph TB
    subgraph "Entry Point"
        CLI[CLI<br/>mcp-hass serve]
    end

    subgraph "Orchestration"
        Server[server.py<br/>MCPHomeAssistantServer]
        Config[ConfigurationManager]
    end

    subgraph "Dependency Injection"
        Context[ToolContext]
    end

    subgraph "Tool Modules"
        Entity[entity.py<br/>2 tools]
        Service[service.py<br/>3 tools]
        Spatial[spatial.py<br/>2 tools]
        Device[device.py<br/>2 tools]
        Bulk[bulk.py<br/>1 tool]
        Camera[camera.py<br/>1 tool]
        YAML[yaml_config.py<br/>1 tool]
    end

    subgraph "Home Assistant"
        HAClient[HomeAssistantClient<br/>Dual REST + WebSocket]
        REST[REST API]
        WS[WebSocket API]
    end

    CLI --> Server
    Server --> Config
    Server --> Context
    Context --> Entity & Service & Spatial & Device & Bulk & Camera & YAML
    Entity & Service & Spatial & Device & Bulk & Camera & YAML --> HAClient
    HAClient --> REST & WS
sequenceDiagram
    participant Client as AI Client
    participant MCP as FastMCP
    participant Tool as Tool Function
    participant HAClient as HomeAssistantClient
    participant HA as Home Assistant

    Client->>MCP: MCP tool call
    MCP->>Tool: Execute tool
    Tool->>HAClient: API call (REST or WebSocket)
    HAClient->>HA: HTTP/WS request
    HA-->>HAClient: Response
    HAClient-->>Tool: Parsed data
    Tool->>Tool: Check token limit
    Tool-->>MCP: JSON result
    MCP-->>Client: MCP response

Usage

MCP Tools

Category

Tool

Description

Entity

find_entities

Discover entities with filtering (domain, area, state, attributes)

Entity

get_entity_history

Historical state data

Service

call_service

Control devices

Service

call_service_bulk

Bulk operations across multiple entities

Service

get_services

List available services

Service

get_service_detail

Service schema details

Spatial

list_areas

Get all areas/zones

Spatial

get_area_devices

Devices in an area

Device

find_devices

Discover devices with filtering

Device

get_device_entities

Entities for a device

Camera

get_camera_snapshot

Capture with intelligent downsampling

Config

reload_yaml_config

Validate and reload YAML config

CLI

mcp-hass serve                    # Start stdio server (default)
mcp-hass serve --transport http   # Start HTTP server
mcp-hass init                     # Create config file
mcp-hass validate                 # Validate configuration and HA connectivity
mcp-hass tools                    # List registered tools
mcp-hass config                   # Show active configuration

Getting Started

Prerequisites

  • Python 3.10+

  • A running Home Assistant instance

  • A Home Assistant long-lived access token (create one here)

Option A: stdio (Claude Desktop)

  1. Install: pipx install mcp-hass

  2. Initialize config: mcp-hass init

  3. Edit ~/.config/mcp-hass/config with your HA_BASE_URL and HA_TOKEN

  4. Validate: mcp-hass validate

  5. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

    {
  "mcpServers": {
    "mcp-hass": {
      "command": "mcp-hass",
      "args": ["serve"]
    }
  }
}

Option B: Docker (HTTP)

  1. Configure environment:

    cp .env.example .env
# Edit .env with HA_BASE_URL, HA_TOKEN, and optionally MCP_HOST_PORT

  2. Launch (builds, starts, and runs smoke tests):

    ./launch.sh

  3. Connect via mcp-remote:

    {
  "mcpServers": {
    "mcp-hass": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp"]
    }
  }
}

    Adjust the port if you changed MCP_HOST_PORT in .env.

Configuration Reference

# Home Assistant (required)
HA_BASE_URL=http://homeassistant.local:8123
HA_TOKEN=your_long_lived_access_token
HA_TIMEOUT=10
WS_RECONNECT_ATTEMPTS=5
HA_SSL_VERIFY=true          # Set to false for self-signed certs

# MCP Server (required)
MCP_SERVER_NAME=MCP-HASS
LOG_LEVEL=INFO
DEBUG_MODE=false

# Docker (optional)
MCP_HOST_PORT=3000          # Host port for Docker compose

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/max-rousseau/mcp-hass'

If you have feedback or need assistance with the MCP directory API, please join our Discord server