---
slug: "homeassistant-homeassistant-mcp"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/oleander/home-assistant-mcp-server@main/README.md"
repo: "https://github.com/oleander/home-assistant-mcp-server"
source_file: "README.md"
branch: "main"
---
# Home Assistant MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for integrating with [Home Assistant](https://www.home-assistant.io/), 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

```bash
# 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

```bash
# 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:

```json
{
  "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](https://github.com/oleander/home-assistant-mcp-server/blob/HEAD/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](https://github.com/oleander/home-assistant-mcp-server/tree/HEAD/LICENSE) file for details.