Home Assistant MCP server for AI agents

The Home Assistant MCP Server enables Large Language Models (LLMs) to control and query your smart home through the Model Context Protocol. It connects to your Home Assistant instance, allowing natural language interactions with your smart home devices through MCP-compatible clients like Claude Desktop.

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 when Home Assistant is not available

Installation

You can install the server 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

Getting an Access Token

To get a long-lived access token:

Log in to your Home Assistant instance
Click on your profile (bottom left)
Scroll down to "Long-Lived Access Tokens"
Create a new token with a descriptive name
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:

Edit your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
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"
      }
    }
  }
}

Restart Claude Desktop

Available Tools

The server provides 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

Security Considerations

This server requires a Home Assistant access token with full access. Keep in mind:

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect