99 lines
2.0 KiB
Markdown
99 lines
2.0 KiB
Markdown
# Home Assistant MCP Server
|
|
|
|
An MCP (Model Context Protocol) server that enables LLMs to interact with Home Assistant through its REST API.
|
|
|
|
## Features
|
|
|
|
- **get_states** - Get entity states (all or specific)
|
|
- **call_service** - Call Home Assistant services (turn on/off lights, switches, etc.)
|
|
- **get_history** - Get historical state data for entities
|
|
- **get_config** - Get Home Assistant configuration
|
|
- **get_services** - List available services
|
|
- **render_template** - Render Jinja2 templates
|
|
- **get_logbook** - Get logbook entries
|
|
- **fire_event** - Fire custom events
|
|
|
|
## Setup
|
|
|
|
### 1. Generate a Long-Lived Access Token
|
|
|
|
1. Log in to your Home Assistant instance
|
|
2. Go to your Profile (click on your name in the sidebar)
|
|
3. Scroll down to "Long-Lived Access Tokens"
|
|
4. Click "Create Token"
|
|
5. Give it a name (e.g., "MCP Server")
|
|
6. Copy the token immediately (it won't be shown again!)
|
|
|
|
### 2. Configure Environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your Home Assistant URL and token:
|
|
|
|
```
|
|
HA_URL=http://your-home-assistant-ip:8123
|
|
HA_TOKEN=your_long_lived_access_token
|
|
```
|
|
|
|
### 3. Install and Build
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Usage
|
|
|
|
### With Claude Desktop
|
|
|
|
Add to your Claude Desktop configuration (`~/.config/Claude/claude_desktop_config.json` on Linux):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"home-assistant": {
|
|
"command": "node",
|
|
"args": ["/path/to/home-assistant-mcp/dist/index.js"],
|
|
"env": {
|
|
"HA_URL": "http://your-home-assistant-ip:8123",
|
|
"HA_TOKEN": "your_long_lived_access_token"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### With Other MCP Clients
|
|
|
|
Run the server:
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
The server communicates via stdio using the MCP protocol.
|
|
|
|
## Example Commands
|
|
|
|
Once connected, you can ask the LLM things like:
|
|
|
|
- "What's the current temperature in the living room?"
|
|
- "Turn on the kitchen lights"
|
|
- "Show me what happened in the last hour"
|
|
- "What's the status of all my lights?"
|
|
- "Set the thermostat to 22 degrees"
|
|
|
|
## Development
|
|
|
|
Watch mode for TypeScript:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|