convez.ai
MCP ServerAutomaçãoAvançado
maximeallanic

Home Assistant MCP Server

maximeallanic/homeassistant-mcp

Integração completa de Claude com Home Assistant via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra Claude e agentes IA com Home Assistant, fornecendo acesso programático completo via REST e WebSocket. Oferece 70+ ferramentas para gerenciar entidades, automações, scripts, dashboards Lovelace, HACS, tablets Fully Kiosk e mais.

Instalação

$npx convez-ai maximeallanic/homeassistant-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Automação residencial inteligente com IA
  • Consultas em tempo real sobre status de dispositivos
  • Criação e gerenciamento de automações por voz/texto
  • Monitoramento e controle de tablets Kiosk
  • Integração de dashboards Lovelace com agentes

Veredito

Solução robusta e bem-documentada para quem usa Home Assistant e quer criar agentes Claude que controlem a casa. Implementação madura com suporte a eventos em tempo real e gerenciamento completo de integrações — ideal para entusiastas de automação avançada.

README

A tradução para o português deste README ainda está na fila.

Home Assistant MCP Server

A comprehensive Model Context Protocol (MCP) server for Home Assistant. Gives Claude agents (and any MCP-compatible AI client) full programmatic access to your Home Assistant instance via REST API and WebSocket — 70+ tools across entity management, automations, scripts, scenes, Lovelace dashboards, HACS, Fully Kiosk tablets, and more.

Features

  • REST + WebSocket — entity states, services, history, logbook, configs, entity registry, device registry
  • Automation & Script management — full CRUD (create, read, update, delete, trigger, trace)
  • Lovelace dashboards — list, get, create, update, delete dashboards; list cards and resources
  • HACS — status, list/install/remove/refresh repositories, get releases
  • Fully Kiosk Browser tablets — load URL, screenshot, screen on/off, restart, set config
  • Camera — get images (auto-resized, base64 JPEG, Pillow-optimized)
  • Real-time events — SSE-based event subscriptions with entity/domain filtering
  • System management — restart/stop HA, validate config, system health, supervisor info
  • Integration management — list, enable, disable, delete, reload integrations; run config flows

Requirements

Installation

git clone https://github.com/maximeallanic/homeassistant-mcp.git
cd homeassistant-mcp
./setup.sh

setup.sh creates a venv/ virtual environment and installs dependencies from requirements.txt.

Configuration

cp .env.example .env

Edit .env:

HA_URL=http://homeassistant.local:8123   # or https://your-ha-domain.com
HA_TOKEN=your_long_lived_access_token_here

How to get a token: Home Assistant → Profile → Long-Lived Access Tokens → Create Token.

Usage

Start the server

./start_server.sh

Or directly:

export HA_URL=http://homeassistant.local:8123
export HA_TOKEN=your_token
python server.py

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "homeassistant": {
      "command": "/path/to/homeassistant-mcp/start_server.sh"
    }
  }
}

Personas Studio (Claude Agent SDK)

Register in your agent's MCP list using start_mcp.sh (loads credentials from .env and activates the .venv):

{
  "name": "ha-history",
  "command": "/path/to/homeassistant-mcp/start_mcp.sh",
  "args": []
}

The MCP is used internally by the home-manager agent with tools prefixed mcp__ha-history__*.

Available Tools

Entity State Management

ToolDescription
get_entity_stateGet current state of an entity
search_entitiesSearch entities by name, domain, or state
set_stateSet/update entity state (virtual state, not device control)
delete_stateDelete an entity state
get_entity_registryGet full entity registry
update_entity_registryUpdate entity name, area, enabled/disabled
enable_entity / disable_entityEnable or disable an entity
get_area_entitiesGet entities in a given area

Service Calls

ToolDescription
call_serviceCall any HA service (domain, service, entity_id, service_data)
call_service_with_responseCall service and return response data (e.g. weather forecasts)
fire_eventFire a custom HA event
handle_intentHandle a HA intent (SetTimer, GetWeather, etc.)
render_templateRender a Jinja2 template

Automations

ToolDescription
get_automationsList all automations
get_automationGet automation details
create_automationCreate automation from config
update_automationUpdate existing automation
delete_automationDelete automation
toggle_automation / turn_on_automation / turn_off_automationControl automation state
trigger_automationManually trigger an automation
reload_automationsReload automations from config
get_automation_traceGet execution trace for debugging

Scripts

ToolDescription
list_scriptsList all scripts
create_scriptCreate a new script
update_scriptUpdate an existing script
delete_scriptDelete a script
reload_scriptsReload all scripts

Scenes

ToolDescription
get_scenesList all scenes
activate_sceneActivate a scene
create_sceneCreate scene from current entity states

Areas & Devices

ToolDescription
get_areasList all areas
create_area / update_area / delete_areaManage areas
get_entities_by_areaGet entities in an area
get_devicesList all devices
get_deviceGet device details
update_deviceRename device or assign to area

Lovelace Dashboards

ToolDescription
list_dashboardsList all dashboards
get_dashboard_configGet full dashboard YAML config
update_dashboard_configSave dashboard config
create_dashboardCreate new dashboard
delete_dashboardDelete a dashboard
list_lovelace_resourcesList registered JS resources
list_lovelace_cardsList all available card types (built-in + HACS)

HACS

ToolDescription
hacs_statusGet HACS status
hacs_list_repositoriesList repos (filter by category)
hacs_repository_infoGet repo details
hacs_downloadInstall/update a repo
hacs_removeUninstall a repo
hacs_refreshRefresh repo metadata
hacs_releasesList available versions

System & Integrations

ToolDescription
get_system_healthSystem health status
get_system_infoHost/OS info
get_supervisor_infoSupervisor info (HA OS only)
check_config / check_config_validValidate HA configuration
restart_homeassistantGraceful HA restart
stop_homeassistantStop HA
get_integrations / list_config_entriesList integrations
reload_integrationReload an integration
enable_integration / disable_integration / delete_integrationManage integrations
start_integration_flow / get_integration_flow / submit_integration_flowRun config flows
get_integration_infoGet integration details

Notifications

ToolDescription
send_notificationSend via any notify service or persistent notification
get_notification_servicesList available notification targets
dismiss_notificationDismiss a persistent notification

Data & History

ToolDescription
get_historyHistorical entity states with filtering
get_logbookLogbook events
get_error_logHA error log
get_calendarsList calendar entities
get_calendar_eventsGet events from a calendar
get_camera_imageGet camera snapshot (resized JPEG, base64)

Real-time Events

ToolDescription
subscribe_eventsSubscribe to HA events via SSE (filter by type/entity/domain)
get_sse_statsGet current SSE subscription stats

WebSocket & Kiosk

ToolDescription
websocket_callGeneric WebSocket command (entity icons, subscribe_trigger, etc.)
fully_kiosk_commandControl Fully Kiosk Browser tablets (load_url, screenshot, screen_on/off, restart)

MCP Resources

The server also exposes MCP resources readable by the client:

  • homeassistant://states — all entity states
  • homeassistant://config — HA system configuration
  • homeassistant://services — all available services
  • homeassistant://events — available event types

Usage Examples

Turn on a light

{
  "tool": "call_service",
  "arguments": {
    "domain": "light",
    "service": "turn_on",
    "entity_id": "light.living_room",
    "service_data": { "brightness": 200, "color_temp": 3000 }
  }
}

Get temperature sensor history

{
  "tool": "get_history",
  "arguments": {
    "entity_ids": ["sensor.living_room_temperature"],
    "start_time": "2024-01-01T00:00:00Z",
    "minimal_response": true
  }
}

Send a mobile notification

{
  "tool": "send_notification",
  "arguments": {
    "message": "Front door opened",
    "title": "Security Alert",
    "target": "mobile_app_myphone"
  }
}

Control a Fully Kiosk tablet

{
  "tool": "fully_kiosk_command",
  "arguments": {
    "device_id": "9bdddc78adfa5d4fd74b98b735dc112f",
    "command": "load_url",
    "url": "http://homeassistant.local:8123/dashboard-kiosk/default"
  }
}

Generic WebSocket command (set entity icon)

{
  "tool": "websocket_call",
  "arguments": {
    "type": "entity_registry/update",
    "data": {
      "entity_id": "light.living_room",
      "icon": "mdi:ceiling-light"
    }
  }
}

Testing

# Basic connectivity test (requires HA_TOKEN)
python tests/test_connection.py

# Tool schema validation (no HA connection needed)
python tests/test_mcp_tools.py

# Tool handler tests with mocks (no HA connection needed)
python tests/test_tool_handlers.py

# Live integration tests (requires HA_TOKEN)
python tests/test_new_features.py

Security

  • Never commit your .env file (it is in .gitignore)
  • Use a dedicated long-lived access token with minimal required permissions
  • If exposing HA externally, use HTTPS and ensure your token is kept secret
  • Prefer internal network access (http://homeassistant.local:8123) over external URLs when possible

Architecture

server.py                    # Main MCP server (70+ tools, REST + WebSocket)
  HomeAssistantClient        # Async HTTP + WebSocket client
  SSEManager                 # Real-time event subscription manager
  MCP tool handlers          # One handler per tool, all async

start_mcp.sh                 # Entry point for Personas Studio (uses .venv)
start_server.sh              # Entry point for other clients (uses venv/)
setup.sh                     # One-time setup (creates venv, installs deps)
mcp_config.json              # MCP server config for Warp terminal
requirements.txt             # Python dependencies (aiohttp, mcp, Pillow)
tests/                       # Test suite (connection, schemas, handlers, integration)

License

MIT — see LICENSE

Ver o original no GitHub

Bom para

Relacionados