homeassistant-mcp

WHAT IT CONNECTS

What homeassistant-mcp gives an AI Agent

• 🎮 **Device Control**: Control any Home Assistant device through natural language
• 🔄 **Real-time Updates**: Get instant updates through Server-Sent Events (SSE)
• 🤖 **Automation Management**: Create, update, and manage automations
• 📊 **State Monitoring**: Track and query device states
• 🔐 **Secure**: Token-based authentication and rate limiting
• 📱 **Mobile Ready**: Works with any HTTP-capable client
• 🔄 Get instant state changes for any device
• 📡 Monitor automation triggers and executions
• 🎯 Subscribe to specific domains or entities
• 📊 Track service calls and script executions
• [Key Features](#key-features)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Basic Setup](#basic-setup)
• [Docker Setup (Recommended)](#docker-setup-recommended)
• [Configuration](#configuration)
• [Development](#development)
• [API Reference](#api-reference)
• [Device Control](#device-control)
• [Add-on Management](#add-on-management)
• [Package Management](#package-management)
• [Automation Management](#automation-management)
• [Natural Language Integration](#natural-language-integration)
• [Troubleshooting](#troubleshooting)
• [Project Status](#project-status)
• [Contributing](#contributing)
• [Resources](#resources)
• [License](#license)
• **Smart Device Control**
• 💡 **Lights**: Brightness, color temperature, RGB color
• 🌡️ **Climate**: Temperature, HVAC modes, fan modes, humidity
• 🚪 **Covers**: Position and tilt control
• 🔌 **Switches**: On/off control
• 🚨 **Sensors & Contacts**: State monitoring
• 🎵 **Media Players**: Playback control, volume, source selection
• 🌪️ **Fans**: Speed, oscillation, direction
• 🔒 **Locks**: Lock/unlock control
• 🧹 **Vacuums**: Start, stop, return to base
• 📹 **Cameras**: Motion detection, snapshots
• **Add-on Management**
• Browse available add-ons
• Install/uninstall add-ons
• Start/stop/restart add-ons
• Version management
• Configuration access
• **Package Management (HACS)**
• Integration with Home Assistant Community Store
• Multiple package types support:
• Custom integrations
• Frontend themes
• Python scripts
• AppDaemon apps
• NetDaemon apps
• Version control and updates
• Repository management
• **Automation Management**
• Create and edit automations
• Advanced configuration options:
• Multiple trigger types
• Complex conditions
• Action sequences
• Execution modes
• Duplicate and modify existing automations
• Enable/disable automation rules
• Trigger automation manually
• **Intelligent Organization**
• Area and floor-based device grouping
• State monitoring and querying
• Smart context awareness
• Historical data access
• **Robust Architecture**
• Comprehensive error handling
• State validation
• Secure API integration
• TypeScript type safety
• Extensive test coverage
• **Node.js** 20.10.0 or higher
• **NPM** package manager
• **Docker Compose** for containerization
• Running **Home Assistant** instance
• Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159))
• **HACS** installed for package management features
• **Supervisor** access for add-on management
• **Clone the repository:**
• **Configure environment:**
• **Build and run with Docker Compose:**
• **Verify the installation:**
• **Update the application:**
• Multi-stage build for optimal image size
• Health checks for container monitoring
• Volume mounting for environment configuration
• Automatic container restart on failure
• Exposed port 3000 for API access
• `HASS_HOST`: Your Home Assistant instance URL
• `HASS_TOKEN`: Long-lived access token for Home Assistant
• `HASS_SOCKET_URL`: WebSocket URL for Home Assistant
• `PORT`: Server port (default: 3000)
• `NODE_ENV`: Environment (production/development)
• `DEBUG`: Enable debug mode (true/false)
• **Development**: Copy `.env.example` to `.env.development`
• **Production**: Copy `.env.example` to `.env.production`
• **Testing**: Copy `.env.example` to `.env.test`
• `state_change`: Emitted when system state changes
• `context_update`: Emitted when context is updated
• `action_executed`: Emitted when an action is completed
• `error`: Emitted when an error occurs
• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error
• 100 requests per minute per IP for regular endpoints
• 1000 requests per minute per IP for WebSocket connections
• **Node.js Version (`toSorted is not a function`)**
• **Solution:** Update to Node.js 20.10.0+
• **Connection Issues**
• Verify Home Assistant is running
• Check `HASS_HOST` accessibility
• Validate token permissions
• Ensure WebSocket connection for real-time updates
• **Add-on Management Issues**
• Verify Supervisor access
• Check add-on compatibility
• Validate system resources
• **HACS Integration Issues**
• Verify HACS installation
• Check HACS integration status
• Validate repository access
• **Automation Issues**
• Verify entity availability
• Check trigger conditions
• Validate service calls
• Monitor execution logs
• Entity, Floor, and Area access
• Device control (Lights, Climate, Covers, Switches, Contacts)
• Add-on management system
• Package management through HACS
• Advanced automation configuration
• Basic state management
• Error handling and validation
• Docker containerization
• Jest testing setup
• TypeScript integration
• Environment variable management
• Home Assistant API integration
• Project documentation
• WebSocket implementation for real-time updates
• Enhanced security features
• Tool organization optimization
• Performance optimization
• Resource context integration
• API documentation generation
• Multi-platform desktop integration
• Advanced error recovery
• Custom prompt testing
• Enhanced macOS integration
• Type safety improvements
• Testing coverage expansion
• Fork the repository
• Create a feature branch
• Implement your changes
• Add tests for new functionality
• Ensure all tests pass
• Submit a pull request
• [MCP Documentation](https://modelcontextprotocol.io/introduction)
• [Home Assistant Docs](https://www.home-assistant.io)
• [HA REST API](https://developers.home-assistant.io/docs/api/rest)
• [HACS Documentation](https://hacs.xyz)
• [TypeScript Documentation](https://www.typescriptlang.org/docs)