Home Assistant MCP Server Model Context Protocol (MCP) server for Home Assistant integration. This Actor provides tools and resources to interact with Home Assistant entities, services, and states via the MCP protocol. What is Home Assistant? Home Assistant is an open-source home automation platform that acts as a central hub for controlling smart devices from different manufacturers. It supports integrations with hundreds of devices and platforms including lights, switches, sensors, climate control, media players, and more. ✨ Control any smart device - If your devices are integrated with Home Assistant, you can control them all through this MCP server! ## Features - 🔌 MCP Protocol Support - Full Model Context Protocol implementation - 🏠 Home Assistant Integration - Direct connection to Home Assistant REST API - 🛠️ Tools Available: - get_states - Get all states from Home Assistant - get_state - Get the state of a specific entity - call_service - Call a Home Assistant service - get_entities - Get all available entities - get_services - Get all available services - 📚 Resources Available: - home-assistant://entities - List of all Home Assistant entities - home-assistant://services - List of all available services - 💰 Pay Per Event - Flexible pricing based on tool and resource usage - 🔄 Standby Mode - Runs as a long-running server for fast response times ## Prerequisites 1. Home Assistant Installation - You need a running Home Assistant instance - Home Assistant is a free, open-source home automation platform - It can be installed on Raspberry Pi, Docker, or as a VM - Installation guide: https://www.home-assistant.io/installation/ 2. Long-Lived Access Token - Create one at: Profile → Long-Lived Access Tokens in Home Assistant 3. (Optional) Smart Device Integration - To control your smart devices: - Set up your devices in Home Assistant using the appropriate integrations - Check the Home Assistant integrations page for available integrations - Common integrations include: lights, switches, sensors, climate control, media players, and more - Once integrated, devices appear as entities in Home Assistant - You can then control them through this MCP server using the call_service tool ## Authentication This Actor runs in standby mode and behaves like an API. No input is required at startup. Instead, you must include your Home Assistant credentials in each request body: - homeAssistantUrl (required in request body): The URL of your Home Assistant instance - Example: https://homeassistant.local:8123 - Example: http://192.168.1.100:8123 - homeAssistantApiKey (required in request body): Long-lived access token from Home Assistant - Create at: Profile → Long-Lived Access Tokens in Home Assistant ## Usage ### Running in Standby Mode This Actor is designed to run in standby mode on the Apify platform. When deployed, it will: 1. Start an HTTP server listening on the configured port 2. Accept MCP requests at the /mcp endpoint 3. Process requests and return responses ### Connecting with MCP Client Once deployed, connect to your Actor using the standby URL: https://me--home-assistant-mcp-server.apify.actor/mcp Important: You must pass your Apify API token in the Authorization header: Authorization: Bearer <YOUR_APIFY_API_TOKEN> ### Example MCP Requests Important: All requests must include homeAssistantUrl and homeAssistantApiKey in the request body. #### List Tools json { "method": "tools/list", "params": {}, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } #### Call a Tool json { "method": "tools/call", "params": { "name": "get_state", "arguments": { "entityId": "light.living_room" } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } #### List Resources json { "method": "resources/list", "params": {}, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } #### Read a Resource json { "method": "resources/read", "params": { "uri": "home-assistant://entities" }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } ## Available Tools ### get_states Get all states from Home Assistant. No parameters required ### get_state Get the state of a specific entity. Parameters: - entityId (required): Entity ID (e.g., light.living_room, switch.coffee_maker, sensor.temperature) Example: json { "method": "tools/call", "params": { "name": "get_state", "arguments": { "entityId": "light.living_room" } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } ### call_service Call a Home Assistant service. Parameters: - domain (required): Service domain (e.g., light, switch, climate, media_player) - service (required): Service name (e.g., turn_on, turn_off, set_temperature) - entityId (required): Entity ID (e.g., light.living_room, switch.coffee_maker) - serviceData (optional): Additional service data Example: json { "method": "tools/call", "params": { "name": "call_service", "arguments": { "domain": "light", "service": "turn_on", "entityId": "light.living_room", "serviceData": { "brightness": 255 } } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } ### get_entities Get all available entities from Home Assistant. Use this to find your device entity IDs. No parameters required Example Response: json [ "light.living_room", "switch.coffee_maker", "sensor.temperature", "climate.thermostat" ] ### get_services Get all available services from Home Assistant. No parameters required ## Available Resources ### home-assistant://entities Returns a JSON list of all Home Assistant entities with their states and attributes. ### home-assistant://services Returns a JSON list of all available Home Assistant services organized by domain. ## Monetization This Actor uses Pay Per Event (PPE) monetization: - tool-request: $0.01 per tool call (get_state, call_service, etc.) - resource-request: $0.005 per resource access (entities list, services list) ## Local Development 1. Install dependencies: bash bun install 2. Run locally: bash bun run start Note: The Actor requires standby mode to run properly. For local testing, you may need to set the APIFY_META_ORIGIN=STANDBY environment variable. ## Deployment 1. Push to Apify: bash apify push 2. Configure Standby Mode: - Go to Actor Settings in Apify Console - Enable "Actor Standby" - Configure standby settings 3. Get Standby URL: - The standby URL will be available in the Actor settings - Format: https://me--home-assistant-mcp-server.apify.actor/mcp ## Security - API Key Protection: Never commit your Home Assistant API key to version control - HTTPS Recommended: Use HTTPS for your Home Assistant URL when possible - Authentication Required: Always use your Apify API token when connecting to the standby endpoint ## Usage Examples This MCP server works with any device that's integrated in Home Assistant. Below are examples for common device types: ### Finding Your Devices 1. List all entities to find your devices: json { "method": "tools/call", "params": { "name": "get_entities", "arguments": {} }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } Look for entities by their domain prefix: - light.* - Lights - switch.* - Switches - sensor.* - Sensors - climate.* - Thermostats/climate control - media_player.* - Media players - And many more... ### Example: Lights json { "method": "tools/call", "params": { "name": "call_service", "arguments": { "domain": "light", "service": "turn_on", "entityId": "light.living_room", "serviceData": { "brightness": 255, "color_name": "red" } } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } ### Example: Switches json { "method": "tools/call", "params": { "name": "call_service", "arguments": { "domain": "switch", "service": "turn_on", "entityId": "switch.coffee_maker" } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } ### Example: Climate Control json { "method": "tools/call", "params": { "name": "call_service", "arguments": { "domain": "climate", "service": "set_temperature", "entityId": "climate.thermostat", "serviceData": { "temperature": 72 } } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } ### Example: Reading Sensors json { "method": "tools/call", "params": { "name": "get_state", "arguments": { "entityId": "sensor.temperature" } }, "homeAssistantUrl": "https://homeassistant.local:8123", "homeAssistantApiKey": "YOUR_LONG_LIVED_ACCESS_TOKEN" } Note: The exact services and entities available depend on how your devices are integrated in your Home Assistant setup. Use get_services and get_entities to discover what's available in your installation. ## Troubleshooting ### Connection Issues - Verify your Home Assistant URL is accessible - Check that your API key is valid and has not expired - Ensure Home Assistant is running and the API is enabled ### Devices Not Found - Verify your devices are integrated in Home Assistant - Check Home Assistant → Settings → Devices & Services - Use get_entities to list all available entities and find your device IDs - Common entity patterns: - Lights: light.* - Switches: switch.* - Sensors: sensor.* - Climate: climate.* - Media players: media_player.* ### MCP Protocol Errors - Verify request format matches MCP protocol specification - Check that required parameters are provided - Review Actor logs for detailed error messages ## Support For issues or questions: - Check the Actor logs in Apify Console - Review Home Assistant API documentation: https://www.home-assistant.io/integrations/api/ - MCP Protocol documentation: https://modelcontextprotocol.io/ ## License ISC