Home Assistant Integration MCP Server

Home Assistant Integration

This MCP server connects AI assistants like Claude to your Home Assistant smart home system, enabling natural language control and querying of your devices, automations, and sensors.

Features

• Query the state of any device or sensor in your smart home
• Control lights, switches, and other entities through natural language
• Get comprehensive summaries of your smart home system
• Troubleshoot automations and entity issues
• Search for specific entities by name, type, or state
• Use guided conversations for common smart home tasks

Installation Options

Docker Installation (Recommended)

1. Make sure you have Docker installed on your system

2. You'll need a Home Assistant long-lived access token:

   • In Home Assistant, go to your profile (click your username in the sidebar)
   • Scroll down to "Long-Lived Access Tokens"
   • Create a new token with a descriptive name like "AI Assistant"
   • Copy the token value (you won't be able to see it again)

3. Configure your AI assistant to use the MCP server by adding the appropriate configuration to your settings.

Manual Installation

If you prefer not to use Docker:

1. Ensure you have Python 3.13+ installed
2. Install uv for package management
3. Clone the repository: git clone https://github.com/voska/hass-mcp
4. Navigate to the directory: cd hass-mcp
5. Copy the example environment file: cp .env.example .env
6. Edit the .env file to add your Home Assistant URL and token
7. Install dependencies: uv pip install -e .
8. Run the server: python -m app.main

Configuration

When setting up the MCP server, you'll need to provide:

• HA_URL: The URL of your Home Assistant instance (e.g., http://homeassistant.local:8123)
• HA_TOKEN: Your Home Assistant long-lived access token

If running Home Assistant on the same machine as the MCP server in Docker:

• Use http://host.docker.internal:8123 for Mac/Windows
• You may need to use --network host in Docker args or use your machine's IP address

Usage Examples

Once configured, you can ask your AI assistant questions like:

• "What's the temperature in the living room?"
• "Turn off all the lights in the kitchen"
• "Is my front door locked?"
• "Give me a summary of all my smart home devices"
• "What automations do I have set up?"
• "Help me troubleshoot why my motion sensor isn't working"

The MCP server handles translating these natural language requests into Home Assistant API calls and formatting the responses in a way that's both informative for you and token-efficient for the AI.