What is Home Assistant Mcp Server

home-assistant-mcp-server is a Model Context Protocol (MCP) server designed to integrate with Home Assistant, enabling large language models (LLMs) to control and query smart home entities using natural language.

Use cases

Use cases include controlling smart home devices, querying device states, managing services, retrieving historical data, and testing configurations in environments where Home Assistant may not be available.

How to use

To use home-assistant-mcp-server, install it globally using ‘bun install -g home-assistant-mcp-server’ or clone the repository and build it from source. Configure the server by creating a .env file with your Home Assistant URL and long-lived access token. Run the server in standard mode or demo mode as needed.

Key features

Key features include natural language querying and control of Home Assistant entities, compatibility with any MCP-compatible client, secure authentication with long-lived access tokens, multiple transport options (stdio and SSE), and a demo mode for testing with mock data.

Where to use

home-assistant-mcp-server is primarily used in smart home environments where integration with Home Assistant is required, allowing users to interact with their smart devices through LLMs.

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:

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.