7610147a19
- Renamed "Sensors" to "Sensors & Contacts" for better accuracy. - Changed section title from "Quick Start" to "Prerequisites" and refined the prerequisites list for clarity. - Added an "Installation" section with detailed setup instructions. - Updated "Usage Guide" to "Configuration" and included a new section for environment variable setup. - Expanded command examples for light, climate, and cover controls to include additional parameters. - Improved troubleshooting section with more detailed entity control issues. - Consolidated resources section for better accessibility.
186 lines
4.0 KiB
Markdown
186 lines
4.0 KiB
Markdown
# Model Context Protocol Server for Home Assistant
|
|
|
|
A 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).
|
|
|
|
## Key Features
|
|
|
|
- **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
|
|
- **Intelligent Organization** 🏠
|
|
- Area and floor-based device grouping
|
|
- State monitoring and querying
|
|
- Smart context awareness
|
|
- **Robust Architecture** 🛠️
|
|
- Comprehensive error handling
|
|
- State validation
|
|
- Secure API integration
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20.10.0 or higher
|
|
- NPM package manager
|
|
- 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))
|
|
|
|
## Installation
|
|
|
|
### Basic Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
|
cd homeassistant-mcp
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build the project
|
|
npm run build
|
|
```
|
|
|
|
### Docker Setup (Recommended)
|
|
|
|
1. Clone and prepare:
|
|
```bash
|
|
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
|
cd homeassistant-mcp
|
|
```
|
|
|
|
2. Configure environment:
|
|
```env
|
|
NODE_ENV=production
|
|
HASS_HOST=your_home_assistant_url
|
|
HASS_TOKEN=your_home_assistant_token
|
|
```
|
|
|
|
3. Launch with Docker Compose:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file with:
|
|
|
|
```env
|
|
HASS_TOKEN=your_home_assistant_token
|
|
HASS_HOST=your_home_assistant_url # e.g., http://homeassistant.local:8123
|
|
PORT=3000 # Optional, defaults to 3000
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm run dev # Development mode
|
|
npm run build # Build project
|
|
npm run start # Production mode
|
|
npx jest --config=jest.config.js # Run tests
|
|
```
|
|
|
|
## Supported Commands
|
|
|
|
### Common Entity Controls
|
|
```json
|
|
{
|
|
"tool": "control",
|
|
"command": "turn_on", // or "turn_off", "toggle"
|
|
"entity_id": "light.living_room"
|
|
}
|
|
```
|
|
|
|
### Light Control
|
|
```json
|
|
{
|
|
"tool": "control",
|
|
"command": "turn_on",
|
|
"entity_id": "light.living_room",
|
|
"brightness": 128,
|
|
"color_temp": 4000,
|
|
"rgb_color": [255, 0, 0]
|
|
}
|
|
```
|
|
|
|
### Climate Control
|
|
```json
|
|
{
|
|
"tool": "control",
|
|
"command": "set_temperature",
|
|
"entity_id": "climate.bedroom",
|
|
"temperature": 22,
|
|
"hvac_mode": "heat",
|
|
"fan_mode": "auto",
|
|
"humidity": 45
|
|
}
|
|
```
|
|
|
|
### Cover Control
|
|
```json
|
|
{
|
|
"tool": "control",
|
|
"command": "set_position",
|
|
"entity_id": "cover.living_room",
|
|
"position": 50,
|
|
"tilt_position": 45
|
|
}
|
|
```
|
|
|
|
## Natural Language Integration
|
|
|
|
### Example Commands
|
|
- "Turn on the living room lights"
|
|
- "Set bedroom temperature to 22 degrees"
|
|
- "Is the front door locked?"
|
|
|
|
### Smart Features
|
|
- Context awareness across conversations
|
|
- Natural parameter interpretation
|
|
- Intelligent error prevention
|
|
- Multi-device orchestration
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
1. Node.js Version (`toSorted is not a function`)
|
|
- Solution: Update to Node.js 20.10.0+
|
|
2. Connection Issues
|
|
- Verify Home Assistant is running
|
|
- Check HASS_HOST accessibility
|
|
- Validate token permissions
|
|
3. Entity Control Issues
|
|
- Verify entity_id exists
|
|
- Check entity domain matches command
|
|
- Ensure parameter values are valid
|
|
|
|
## Project Status
|
|
|
|
✅ **Complete**
|
|
- Entity, Floor, and Area access
|
|
- Device control (Lights, Climate, Covers, Switches, Contacts)
|
|
- Basic state management
|
|
- Error handling and validation
|
|
|
|
🚧 **In Progress**
|
|
- Custom prompt testing
|
|
- Resource context integration
|
|
- Tool organization optimization
|
|
|
|
## Contributing
|
|
|
|
1. Fork repository
|
|
2. Create feature branch
|
|
3. Submit pull request
|
|
|
|
## Resources
|
|
|
|
- [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)
|
|
|
|
## License
|
|
|
|
MIT License - See [LICENSE](LICENSE) file
|