Model Context Protocol Server for Home Assistant

1# Model Context Protocol Server for Home Assistant
2 
3The server uses the MCP protocol to share access to a local Home Assistant instance with an LLM application.
4 
5A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.
6 
7![License](https://img.shields.io/badge/license-MIT-blue.svg)
8![Node.js](https://img.shields.io/badge/node-%3E%3D20.10.0-green.svg)
9![Docker Compose](https://img.shields.io/badge/docker-compose-%3E%3D1.27.0-blue.svg)
10![NPM](https://img.shields.io/badge/npm-%3E%3D7.0.0-orange.svg)
11![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)
12![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)
13 
14## Features
15 
16- 🎮 **Device Control**: Control any Home Assistant device through natural language
17- 🔄 **Real-time Updates**: Get instant updates through Server-Sent Events (SSE)
18- 🤖 **Automation Management**: Create, update, and manage automations
19- 📊 **State Monitoring**: Track and query device states
20- 🔐 **Secure**: Token-based authentication and rate limiting
21- 📱 **Mobile Ready**: Works with any HTTP-capable client
22 
23## Real-time Updates with SSE
24 
25The server includes a powerful Server-Sent Events (SSE) system that provides real-time updates from your Home Assistant instance. This allows you to:
26 
27- 🔄 Get instant state changes for any device
28- 📡 Monitor automation triggers and executions
29- 🎯 Subscribe to specific domains or entities
30- 📊 Track service calls and script executions
31 
32### Quick SSE Example
33 
34```javascript
35const eventSource = new EventSource(
36  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
37);
38 
39eventSource.onmessage = (event) => {
40  const data = JSON.parse(event.data);
41  console.log('Update received:', data);
42};
43```
44 
45See [SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system.
46 
47## Table of Contents
48 
49- [Key Features](#key-features)
50- [Prerequisites](#prerequisites)
51- [Installation](#installation)
52  - [Basic Setup](#basic-setup)
53  - [Docker Setup (Recommended)](#docker-setup-recommended)
54- [Configuration](#configuration)
55- [Development](#development)
56- [API Reference](#api-reference)
57  - [Device Control](#device-control)
58  - [Add-on Management](#add-on-management)
59  - [Package Management](#package-management)
60  - [Automation Management](#automation-management)
61- [Natural Language Integration](#natural-language-integration)
62- [Troubleshooting](#troubleshooting)
63- [Project Status](#project-status)
64- [Contributing](#contributing)
65- [Resources](#resources)
66- [License](#license)
67 
68## Key Features
69 
70### Core Functionality 🎮
71- **Smart Device Control**
72  - 💡 **Lights**: Brightness, color temperature, RGB color
73  - 🌡️ **Climate**: Temperature, HVAC modes, fan modes, humidity
74  - 🚪 **Covers**: Position and tilt control
75  - 🔌 **Switches**: On/off control
76  - 🚨 **Sensors & Contacts**: State monitoring
77  - 🎵 **Media Players**: Playback control, volume, source selection
78  - 🌪️ **Fans**: Speed, oscillation, direction
79  - 🔒 **Locks**: Lock/unlock control
80  - 🧹 **Vacuums**: Start, stop, return to base
81  - 📹 **Cameras**: Motion detection, snapshots
82 
83### System Management 🛠️
84- **Add-on Management**
85  - Browse available add-ons
86  - Install/uninstall add-ons
87  - Start/stop/restart add-ons
88  - Version management
89  - Configuration access
90 
91- **Package Management (HACS)**
92  - Integration with Home Assistant Community Store
93  - Multiple package types support:
94    - Custom integrations
95    - Frontend themes
96    - Python scripts
97    - AppDaemon apps
98    - NetDaemon apps
99  - Version control and updates
100  - Repository management
101 
102- **Automation Management**
103  - Create and edit automations
104  - Advanced configuration options:
105    - Multiple trigger types
106    - Complex conditions
107    - Action sequences
108    - Execution modes
109  - Duplicate and modify existing automations
110  - Enable/disable automation rules
111  - Trigger automation manually
112 
113### Architecture Features 🏗️
114- **Intelligent Organization**
115  - Area and floor-based device grouping
116  - State monitoring and querying
117  - Smart context awareness
118  - Historical data access
119 
120- **Robust Architecture**
121  - Comprehensive error handling
122  - State validation
123  - Secure API integration
124  - TypeScript type safety
125  - Extensive test coverage
126 
127## Prerequisites
128 
129- **Node.js** 20.10.0 or higher
130- **NPM** package manager
131- **Docker Compose** for containerization
132- Running **Home Assistant** instance
133- Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159))
134- **HACS** installed for package management features
135- **Supervisor** access for add-on management
136 
137## Installation
138 
139### Basic Setup
140 
141```bash
142# Clone the repository
143git clone https://github.com/tevonsb/homeassistant-mcp.git
144cd homeassistant-mcp
145 
146# Install dependencies
147npm install
148 
149# Build the project
150npm run build
151```
152 
153### Docker Setup (Recommended)
154 
155The project includes Docker support for easy deployment and consistent environments across different platforms.
156 
1571. **Clone the repository:**
158    ```bash
159    git clone https://github.com/tevonsb/homeassistant-mcp.git
160    cd homeassistant-mcp
161    ```
162 
1632. **Configure environment:**
164    ```bash
165    cp .env.example .env
166    ```
167    Edit the `.env` file with your Home Assistant configuration:
168    ```env
169    # Home Assistant Configuration
170    HASS_HOST=http://homeassistant.local:8123
171    HASS_TOKEN=your_home_assistant_token
172    HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
173 
174    # Server Configuration
175    PORT=3000
176    NODE_ENV=production
177    DEBUG=false
178    ```
179 
1803. **Build and run with Docker Compose:**
181    ```bash
182    # Build and start the containers
183    docker compose up -d
184 
185    # View logs
186    docker compose logs -f
187 
188    # Stop the service
189    docker compose down
190    ```
191 
1924. **Verify the installation:**
193    The server should now be running at `http://localhost:3000`. You can check the health endpoint at `http://localhost:3000/health`.
194 
1955. **Update the application:**
196    ```bash
197    # Pull the latest changes
198    git pull
199 
200    # Rebuild and restart the containers
201    docker compose up -d --build
202    ```
203 
204#### Docker Configuration
205 
206The Docker setup includes:
207- Multi-stage build for optimal image size
208- Health checks for container monitoring
209- Volume mounting for environment configuration
210- Automatic container restart on failure
211- Exposed port 3000 for API access
212 
213#### Docker Compose Environment Variables
214 
215All environment variables can be configured in the `.env` file. The following variables are supported:
216- `HASS_HOST`: Your Home Assistant instance URL
217- `HASS_TOKEN`: Long-lived access token for Home Assistant
218- `HASS_SOCKET_URL`: WebSocket URL for Home Assistant
219- `PORT`: Server port (default: 3000)
220- `NODE_ENV`: Environment (production/development)
221- `DEBUG`: Enable debug mode (true/false)
222 
223## Configuration
224 
225### Environment Variables
226 
227```env
228# Home Assistant Configuration
229HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
230HASS_TOKEN=your_home_assistant_token       # Long-lived access token
231HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL
232 
233# Server Configuration
234PORT=3000                # Server port (default: 3000)
235NODE_ENV=production     # Environment (production/development)
236DEBUG=false            # Enable debug mode
237 
238# Test Configuration
239TEST_HASS_HOST=http://localhost:8123  # Test instance URL
240TEST_HASS_TOKEN=test_token           # Test token
241```
242 
243### Configuration Files
244 
2451. **Development**: Copy `.env.example` to `.env.development`
2462. **Production**: Copy `.env.example` to `.env.production`
2473. **Testing**: Copy `.env.example` to `.env.test`
248 
249### Adding to Claude Desktop (or other clients)
250 
251To use your new Home Assistant MCP server, you can add Claude Desktop as a client. Add the following to the configuration. Note this will run the MCP within claude and does not work with the Docker method.
252 
253```
254{
255  "homeassistant": {
256    "command": "node",
257    "args": [<path/to/your/dist/folder>]
258    "env": {
259      NODE_ENV=development
260      HASS_HOST=http://homeassistant.local:8123
261      HASS_TOKEN=your_home_assistant_token
262      PORT=3000
263      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
264      LOG_LEVEL=debug
265    }
266  }
267}
268 
269```
270 
271 
272 
273## API Reference
274 
275### Device Control
276 
277#### Common Entity Controls
278```json
279{
280  "tool": "control",
281  "command": "turn_on",  // or "turn_off", "toggle"
282  "entity_id": "light.living_room"
283}
284```
285 
286#### Light Control
287```json
288{
289  "tool": "control",
290  "command": "turn_on",
291  "entity_id": "light.living_room",
292  "brightness": 128,
293  "color_temp": 4000,
294  "rgb_color": [255, 0, 0]
295}
296```
297 
298### Add-on Management
299 
300#### List Available Add-ons
301```json
302{
303  "tool": "addon",
304  "action": "list"
305}
306```
307 
308#### Install Add-on
309```json
310{
311  "tool": "addon",
312  "action": "install",
313  "slug": "core_configurator",
314  "version": "5.6.0"
315}
316```
317 
318#### Manage Add-on State
319```json
320{
321  "tool": "addon",
322  "action": "start",  // or "stop", "restart"
323  "slug": "core_configurator"
324}
325```
326 
327### Package Management
328 
329#### List HACS Packages
330```json
331{
332  "tool": "package",
333  "action": "list",
334  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
335}
336```
337 
338#### Install Package
339```json
340{
341  "tool": "package",
342  "action": "install",
343  "category": "integration",
344  "repository": "hacs/integration",
345  "version": "1.32.0"
346}
347```
348 
349### Automation Management
350 
351#### Create Automation
352```json
353{
354  "tool": "automation_config",
355  "action": "create",
356  "config": {
357    "alias": "Motion Light",
358    "description": "Turn on light when motion detected",
359    "mode": "single",
360    "trigger": [
361      {
362        "platform": "state",
363        "entity_id": "binary_sensor.motion",
364        "to": "on"
365      }
366    ],
367    "action": [
368      {
369        "service": "light.turn_on",
370        "target": {
371          "entity_id": "light.living_room"
372        }
373      }
374    ]
375  }
376}
377```
378 
379#### Duplicate Automation
380```json
381{
382  "tool": "automation_config",
383  "action": "duplicate",
384  "automation_id": "automation.motion_light"
385}
386```
387 
388### Core Functions
389 
390#### State Management
391```http
392GET /api/state
393POST /api/state
394```
395 
396Manages the current state of the system.
397 
398**Example Request:**
399```json
400POST /api/state
401{
402  "context": "living_room",
403  "state": {
404    "lights": "on",
405    "temperature": 22
406  }
407}
408```
409 
410#### Context Updates
411```http
412POST /api/context
413```
414 
415Updates the current context with new information.
416 
417**Example Request:**
418```json
419POST /api/context
420{
421  "user": "john",
422  "location": "kitchen",
423  "time": "morning",
424  "activity": "cooking"
425}
426```
427 
428### Action Endpoints
429 
430#### Execute Action
431```http
432POST /api/action
433```
434 
435Executes a specified action with given parameters.
436 
437**Example Request:**
438```json
439POST /api/action
440{
441  "action": "turn_on_lights",
442  "parameters": {
443    "room": "living_room",
444    "brightness": 80
445  }
446}
447```
448 
449#### Batch Actions
450```http
451POST /api/actions/batch
452```
453 
454Executes multiple actions in sequence.
455 
456**Example Request:**
457```json
458POST /api/actions/batch
459{
460  "actions": [
461    {
462      "action": "turn_on_lights",
463      "parameters": {
464        "room": "living_room"
465      }
466    },
467    {
468      "action": "set_temperature",
469      "parameters": {
470        "temperature": 22
471      }
472    }
473  ]
474}
475```
476 
477### Query Functions
478 
479#### Get Available Actions
480```http
481GET /api/actions
482```
483 
484Returns a list of all available actions.
485 
486**Example Response:**
487```json
488{
489  "actions": [
490    {
491      "name": "turn_on_lights",
492      "parameters": ["room", "brightness"],
493      "description": "Turns on lights in specified room"
494    },
495    {
496      "name": "set_temperature",
497      "parameters": ["temperature"],
498      "description": "Sets temperature in current context"
499    }
500  ]
501}
502```
503 
504#### Context Query
505```http
506GET /api/context?type=current
507```
508 
509Retrieves context information.
510 
511**Example Response:**
512```json
513{
514  "current_context": {
515    "user": "john",
516    "location": "kitchen",
517    "time": "morning",
518    "activity": "cooking"
519  }
520}
521```
522 
523### WebSocket Events
524 
525The server supports real-time updates via WebSocket connections.
526 
527```javascript
528// Client-side connection example
529const ws = new WebSocket('ws://localhost:3000/ws');
530 
531ws.onmessage = (event) => {
532  const data = JSON.parse(event.data);
533  console.log('Received update:', data);
534};
535```
536 
537#### Supported Events
538 
539- `state_change`: Emitted when system state changes
540- `context_update`: Emitted when context is updated
541- `action_executed`: Emitted when an action is completed
542- `error`: Emitted when an error occurs
543 
544**Example Event Data:**
545```json
546{
547  "event": "state_change",
548  "data": {
549    "previous_state": {
550      "lights": "off"
551    },
552    "current_state": {
553      "lights": "on"
554    },
555    "timestamp": "2024-03-20T10:30:00Z"
556  }
557}
558```
559 
560### Error Handling
561 
562All endpoints return standard HTTP status codes:
563 
564- 200: Success
565- 400: Bad Request
566- 401: Unauthorized
567- 403: Forbidden
568- 404: Not Found
569- 500: Internal Server Error
570 
571**Error Response Format:**
572```json
573{
574  "error": {
575    "code": "INVALID_PARAMETERS",
576    "message": "Missing required parameter: room",
577    "details": {
578      "missing_fields": ["room"]
579    }
580  }
581}
582```
583 
584### Rate Limiting
585 
586The API implements rate limiting to prevent abuse:
587 
588- 100 requests per minute per IP for regular endpoints
589- 1000 requests per minute per IP for WebSocket connections
590 
591When rate limit is exceeded, the server returns:
592 
593```json
594{
595  "error": {
596    "code": "RATE_LIMIT_EXCEEDED",
597    "message": "Too many requests",
598    "reset_time": "2024-03-20T10:31:00Z"
599  }
600}
601```
602 
603### Example Usage
604 
605#### Using curl
606```bash
607# Get current state
608curl -X GET \
609  http://localhost:3000/api/state \
610  -H 'Authorization: ApiKey your_api_key_here'
611 
612# Execute action
613curl -X POST \
614  http://localhost:3000/api/action \
615  -H 'Authorization: ApiKey your_api_key_here' \
616  -H 'Content-Type: application/json' \
617  -d '{
618    "action": "turn_on_lights",
619    "parameters": {
620      "room": "living_room",
621      "brightness": 80
622    }
623  }'
624```
625 
626#### Using JavaScript
627```javascript
628// Execute action
629async function executeAction() {
630  const response = await fetch('http://localhost:3000/api/action', {
631    method: 'POST',
632    headers: {
633      'Authorization': 'ApiKey your_api_key_here',
634      'Content-Type': 'application/json'
635    },
636    body: JSON.stringify({
637      action: 'turn_on_lights',
638      parameters: {
639        room: 'living_room',
640        brightness: 80
641      }
642    })
643  });
644  
645  const data = await response.json();
646  console.log('Action result:', data);
647}
648```
649 
650## Development
651 
652```bash
653# Development mode with hot reload
654npm run dev
655 
656# Build project
657npm run build
658 
659# Production mode
660npm run start
661 
662# Run tests
663npx jest --config=jest.config.cjs
664 
665# Run tests with coverage
666npx jest --coverage
667 
668# Lint code
669npm run lint
670 
671# Format code
672npm run format
673```
674 
675## Troubleshooting
676 
677### Common Issues
678 
6791. **Node.js Version (`toSorted is not a function`)**
680   - **Solution:** Update to Node.js 20.10.0+
681   ```bash
682   nvm install 20.10.0
683   nvm use 20.10.0
684   ```
685 
6862. **Connection Issues**
687   - Verify Home Assistant is running
688   - Check `HASS_HOST` accessibility
689   - Validate token permissions
690   - Ensure WebSocket connection for real-time updates
691 
6923. **Add-on Management Issues**
693   - Verify Supervisor access
694   - Check add-on compatibility
695   - Validate system resources
696 
6974. **HACS Integration Issues**
698   - Verify HACS installation
699   - Check HACS integration status
700   - Validate repository access
701 
7025. **Automation Issues**
703   - Verify entity availability
704   - Check trigger conditions
705   - Validate service calls
706   - Monitor execution logs
707 
708## Project Status
709 
710✅ **Complete**
711- Entity, Floor, and Area access
712- Device control (Lights, Climate, Covers, Switches, Contacts)
713- Add-on management system
714- Package management through HACS
715- Advanced automation configuration
716- Basic state management
717- Error handling and validation
718- Docker containerization
719- Jest testing setup
720- TypeScript integration
721- Environment variable management
722- Home Assistant API integration
723- Project documentation
724 
725🚧 **In Progress**
726- WebSocket implementation for real-time updates
727- Enhanced security features
728- Tool organization optimization
729- Performance optimization
730- Resource context integration
731- API documentation generation
732- Multi-platform desktop integration
733- Advanced error recovery
734- Custom prompt testing
735- Enhanced macOS integration
736- Type safety improvements
737- Testing coverage expansion
738 
739## Contributing
740 
7411. Fork the repository
7422. Create a feature branch
7433. Implement your changes
7444. Add tests for new functionality
7455. Ensure all tests pass
7466. Submit a pull request
747 
748## Resources
749 
750- [MCP Documentation](https://modelcontextprotocol.io/introduction)
751- [Home Assistant Docs](https://www.home-assistant.io)
752- [HA REST API](https://developers.home-assistant.io/docs/api/rest)
753- [HACS Documentation](https://hacs.xyz)
754- [TypeScript Documentation](https://www.typescriptlang.org/docs)
755 
756## License
757 
758MIT License - See [LICENSE](LICENSE) file
759