Home Assistant MCP Server

A Model Context Protocol (MCP) server for integrating with Home Assistant, allowing LLMs to control and query your smart home.

Features

• Query and control Home Assistant entities via natural language
• Works with any MCP-compatible client (like Claude Desktop)
• Provides tools for state management, service calls, history, and more
• Secure authentication using Home Assistant long-lived access tokens
• Multiple transport options (stdio for local processes, SSE for remote clients)
• Demo mode with mock data for testing and demonstration when Home Assistant is not available

Installation

# Install globally using bun
bun install -g home-assistant-mcp-server

# Or install from source
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link

Configuration

Create a .env file in your current directory with the following variables:

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)

Environment Variables

| Variable | Required | Default | Description | | ------------ | -------- | ------- | ------------------------------------------------------------------------------------------ | | HASS_URL | Yes | - | URL to your Home Assistant instance (e.g., http://homeassistant.local:8123) | | HASS_TOKEN | Yes | - | Long-lived access token for authenticating with Home Assistant | | PORT | No | 3000 | Port number for the HTTP server when using HTTP/SSE transport | | HASS_MOCK | No | false | When set to "true", enables mock data mode for testing without a Home Assistant connection |

To get a long-lived access token:

1. Log in to your Home Assistant instance
2. Click on your profile (bottom left)
3. Scroll down to "Long-Lived Access Tokens"
4. Create a new token with a descriptive name
5. Copy the token value (you won't see it again)

Usage

Running as a standalone server

# Standard mode (requires a running Home Assistant instance)
home-assistant-mcp-server                # Start with HTTP/SSE transport
home-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication

# Demo mode (with mock data when Home Assistant is unavailable)
home-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data
home-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data

Integration with Claude Desktop

To use with Claude Desktop:

1. Edit your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "homeassistant": {
      "command": "home-assistant-mcp-server"
      "env": {
        "HASS_URL": "http://your-home-assistant:8123",
        "HASS_TOKEN": "your_token_here",
        "HASS_MOCK": "true"
      }
    }
  }
}

If you have Home Assistant running, simply remove the --mock flag and set HASS_MOCK to false.

3. Restart Claude Desktop

Available Tools

The server exposes several tools for interacting with Home Assistant:

• states - Query entity states
• lights - List lights
• light - Control a light
• service - Call Home Assistant services
• history - Retrieve historical entity data
• services - List available services
• config - Get Home Assistant configuration
• domains - List available domains
• error_log - Get Home Assistant error log
• devices - Get all devices in Home Assistant

For detailed usage examples, see docs/hass-mcp.md.

Security

This server requires a Home Assistant access token with full access. Consider these security recommendations:

• Only run the server on trusted networks
• Use HTTPS if exposing the server remotely
• Keep your .env file secure and don't commit it to source control
• Consider using a token with limited permissions when possible

License

This project is licensed under the MIT License - see the LICENSE file for details.