amattas/homeassistant-mcp-azfn

Home Assistant MCP Azure Functions

Model Context Protocol (MCP) server for Home Assistant device control and monitoring, deployed as an Azure Function.

Features

• 46 MCP Tools for comprehensive home automation
• Device control (lights, switches, covers, locks, climate)
• Sensor categorization (weather, pool, air quality, etc.)
• Scene and automation management
• Area-based device queries
• WebSocket + REST API support
• Optional Redis caching
• Serverless deployment via Azure Functions (Consumption plan)

Prerequisites

• Python 3.11+
• Azure Functions Core Tools (npm install -g azure-functions-core-tools@4)
• Azure account (for deployment)
• Home Assistant instance (local or Nabu Casa)
• Home Assistant Long-Lived Access Token

Local Development Setup

1. Install Dependencies

cd homeassistant-mcp-azfn
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Get Home Assistant Access Token

1. Open Home Assistant
2. Go to Profile (bottom left)
3. Scroll to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Copy the token

3. Configuration

Create local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "HA_URL": "https://homeassistant.local:8123",
    "HA_TOKEN": "your_long_lived_access_token",
    "HA_VERIFY_SSL": "true"
  }
}

Connection Options:

• Local: http://homeassistant.local:8123 or http://192.168.1.x:8123
• Nabu Casa: https://abcdef123456.ui.nabu.casa

4. Run Locally

func start

Test at http://localhost:7071/api/mcp

Available MCP Tools (46+ Total)

Device Control (15 tools)

• turn_on / turn_off / toggle - Control any device
• set_brightness - Adjust light brightness (0-255)
• set_temperature - Climate control
• open_cover / close_cover - Blinds, garage doors
• lock_door / unlock_door - Smart locks

Sensor Queries (9 categories)

• get_weather_sensors - Temperature, humidity, forecast
• get_pool_sensors - Pool equipment monitoring
• get_air_quality_sensors - AQI, CO2, VOC levels
• get_hvac_sensors - HVAC system status
• get_indoor_temp_sensors - Interior temperature
• get_security_sensors - Door/window, motion, cameras
• get_energy_sensors - Power usage
• get_outdoor_sensors - Exterior monitoring
• get_other_sensors - Miscellaneous sensors

State Queries (10 tools)

• get_states - Get entity states with filtering
• get_all_entities - List all entities
• get_entities_by_area - Filter by room/area
• get_entities_by_domain - Filter by type

Area Management (5 tools)

• get_areas - List all areas/rooms
• get_devices_in_area - Devices by location
• get_entities_in_area - Entities by location

Automation (7 tools)

• activate_scene - Trigger scenes
• run_script - Execute scripts
• trigger_automation - Run automations
• call_service - Call any HA service

Azure Deployment

1. Create Function App

az functionapp create \
  --resource-group your-resource-group \
  --name homeassistant-mcp \
  --storage-account yourstorageaccount \
  --consumption-plan-location eastus \
  --runtime python \
  --runtime-version 3.11 \
  --functions-version 4

2. Configure Settings

az functionapp config appsettings set \
  --name homeassistant-mcp \
  --resource-group your-resource-group \
  --settings \
    HA_URL="https://your-ha-instance.com" \
    HA_TOKEN="your_token" \
    HA_VERIFY_SSL="true"

3. Deploy

func azure functionapp publish homeassistant-mcp

Connect to Claude Desktop

{
  "mcpServers": {
    "homeassistant": {
      "url": "http://localhost:7071/api/mcp",
      "transport": "http"
    }
  }
}

Caching (Optional)

Enable Redis caching for improved performance:

Cache TTLs:

• Entity states: 3 seconds (real-time critical)
• Device list: 1800 seconds (30 minutes)
• Areas: 3600 seconds (1 hour)

Sensor Categorization

The service includes built-in sensor categorization for 345+ sensors across 9 categories. This helps organize large Home Assistant installations with many devices.

Troubleshooting

Connection Issues:

• Verify HA_URL is accessible
• Check HA_TOKEN is valid
• For SSL errors, try HA_VERIFY_SSL=false (local only)

WebSocket Fallback:

• REST API failures automatically fall back to WebSocket
• WebSocket provides access to 24+ areas when REST unavailable

Performance:

• Use domain/area filters to reduce response size
• Enable Redis caching for frequently accessed data
• Limit queries to specific entity IDs when possible

Project Structure

homeassistant-mcp-azfn/
├── function_app.py          # Azure Functions entry point
├── host.json                # Functions runtime config
├── requirements.txt         # Python dependencies
├── services/
│   ├── homeassistant.py    # HA service (3,191 lines)
│   └── cache.py            # Redis caching layer
├── helpers/
│   └── sensor_categorizer.py  # Sensor categorization
└── tests/                  # Test suite (optional)

License

MIT