Home Assistant MCP Server

# Home Assistant MCP Server A comprehensive Model Context Protocol (MCP) server for integrating with Home Assistant. This server provides **60 tools** and resources to interact with your Home Assistant instance via the REST API, enabling full smart home management and automation. ## 🚀 Features Overview **60 Total Tools** across **9 Major Categories** for comprehensive Home Assistant management: ### 🔧 **Core Operations** (13 tools) - **Entity State Management**: Get, set, update, and delete entity states - **Service Calls**: Execute Home Assistant services with full response support - **Entity Search**: Advanced search with filtering by name, domain, or state - **Event Handling**: Fire custom events with data payloads - **Template Rendering**: Render Home Assistant templates with live data ### 🏠 **Area & Device Management** (8 tools) - **Area Management**: Create, update, delete areas/zones with aliases - **Device Registry**: List, configure, and manage all Home Assistant devices - **Entity Organization**: Assign entities to areas, bulk area operations - **Device Assignment**: Move devices between areas, enable/disable devices ### 🖥️ **System Management** (6 tools) - **System Control**: Restart/stop Home Assistant safely - **Health Monitoring**: Check system health and component status - **Configuration Validation**: Validate configs before applying changes - **Supervisor Integration**: Get supervisor info (Home Assistant OS) ### 🔌 **Integration Management** (6 tools) - **Integration Lifecycle**: List, enable, disable, delete integrations - **Integration Troubleshooting**: Reload integrations, get detailed info - **Dynamic Management**: Programmatically manage integration configurations ### 🔔 **Notification Services** (3 tools) - **Multi-Channel Notifications**: Send via mobile apps, persistent notifications - **Service Discovery**: List all available notification services - **Notification Management**: Dismiss persistent notifications ### 📋 **Entity Registry Management** (4 tools) - **Entity Configuration**: Update entity names, areas, enabled/disabled status - **Bulk Operations**: Enable/disable multiple entities - **Registry Information**: Get detailed entity registry data ### 🤖 **Automation & Scene Management** (12 tools) - **Automation Control**: Create, update, delete, trigger automations - **Scene Management**: Activate scenes, create new scenes from current states - **Automation Debugging**: Get execution traces and troubleshooting data - **Lifecycle Management**: Full CRUD operations for automations ### 📊 **Data & History** (4 tools) - **Historical Data**: Advanced history queries with filtering options - **Logbook Access**: Get event history and entity changes - **Error Logs**: Retrieve Home Assistant error logs for debugging ### 🎥 **Calendar & Media** (4 tools) - **Calendar Integration**: List calendars and get events with date ranges - **Camera Support**: Get images from camera entities (base64 encoded) - **Intent Processing**: Handle Home Assistant voice/text intents - **Real-time Events**: Subscribe to live Home Assistant events via SSE ## Installation 1. Clone this repository: ```bash git clone https://github.com/cronus42/homeassistant-mcp.git cd homeassistant-mcp ``` 2. Run the setup script: ```bash ./setup.sh ``` 3. Get your Home Assistant Long-Lived Access Token: - Log into your Home Assistant web interface - Go to Profile (click on your user name in bottom left) - Scroll down to "Long-lived access tokens" - Click "Create Token" - Give it a name (e.g., "MCP Server") - Copy the token 4. Configure your settings: ```bash cp .env.example .env # Edit .env with your Home Assistant URL and token ``` 5. Test the connection: ```bash python tests/test_connection.py ``` ## Usage with MCP Clients ### Warp Terminal Integration 1. Run the setup script: ```bash ./setup.sh ``` 2. Configure Warp to use the MCP server: ```bash warp mcp add-server --config mcp_config.json ``` Or manually start the server: ```bash ./start_server.sh ``` ### Claude Desktop Configuration Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "homeassistant": { "command": "/path/to/homeassistant-mcp/start_server.sh", "env": {}, "args": [] } } } ``` ## Available Tools ### `get_entity_state` Get the current state of a specific Home Assistant entity. ```json { "entity_id": "light.living_room" } ``` ### `call_service` Call a Home Assistant service to control devices. ```json { "domain": "light", "service": "turn_on", "entity_id": "light.living_room", "service_data": { "brightness": 255, "color_temp": 3000 } } ``` ### `search_entities` Search for entities by name, domain, or state. ```json { "query": "temperature", "domain": "sensor" } ``` ### `fire_event` Fire a custom event in Home Assistant. ```json { "event_type": "custom_automation_trigger", "event_data": { "source": "mcp_server", "action": "test" } } ``` ### `get_history` Get historical data for specific entities. ```json { "entity_ids": ["sensor.temperature", "light.living_room"], "start_time": "2024-01-01T00:00:00Z" } ``` ### New Feature Examples #### Area Management ```json { "tool": "get_areas", "arguments": {} } ``` #### Create and Manage Areas ```json { "tool": "create_area", "arguments": { "name": "Home Office", "aliases": ["office", "workspace"] } } ``` #### Device Management ```json { "tool": "get_devices", "arguments": {} } ``` #### System Health Check ```json { "tool": "get_system_health", "arguments": {} } ``` #### Send Notifications ```json { "tool": "send_notification", "arguments": { "message": "Security Alert: Front door opened", "title": "Security System", "target": "mobile_app_phone" } } ``` #### Integration Management ```json { "tool": "get_integrations", "arguments": {} } ``` ## Testing The server includes comprehensive test suites: ### Run All Tests ```bash # Test tool definitions and schemas python tests/test_mcp_tools.py # Test tool handlers with mocking python tests/test_tool_handlers.py # Test with real Home Assistant (requires HA_TOKEN) python tests/test_new_features.py # Test basic connection python tests/test_connection.py ``` ### Test Results - ✅ **60/60 tools** properly defined - ✅ **All schemas** validated - ✅ **All tool handlers** working correctly - ✅ **100% test coverage** for new features ## Available Resources - `homeassistant://states` - Current state of all entities - `homeassistant://config` - Home Assistant configuration - `homeassistant://services` - Available services - `homeassistant://events` - Available event types ## Usage Examples ### Turn on a light ```json { "tool": "call_service", "arguments": { "domain": "light", "service": "turn_on", "entity_id": "light.living_room" } } ``` ### Check temperature sensors ```json { "tool": "search_entities", "arguments": { "query": "temperature", "domain": "sensor" } } ``` ### Get current state of all lights ```json { "tool": "search_entities", "arguments": { "query": "light", "domain": "light" } } ``` ## Security - Store your Home Assistant token securely - Use environment variables for configuration - Consider network security between your MCP client and Home Assistant - Limit token permissions if possible ## Troubleshooting ### Connection Issues - Verify Home Assistant URL is accessible - Check if Home Assistant API is enabled - Ensure token is valid and has proper permissions ### Authentication Errors - Regenerate long-lived access token - Check token format (should be a long string) - Verify token is set in environment variable ### Service Call Failures - Check entity IDs exist in Home Assistant - Verify service names and parameters - Check Home Assistant logs for errors ## Contributing Feel free to submit issues and enhancement requests!