e46b72b914
- Introduced `claude_desktop_setup.sh` to automate the installation and configuration of MCP integration for Claude Desktop, including Node.js installation via nvm and Brave Search MCP setup. - Updated README.md to reflect new setup instructions, key features, and quick start guide for using the MCP with Home Assistant and Claude Desktop. - Enhanced configuration management by detailing environment variable setup and providing examples for user configurations.
146 lines
3.1 KiB
Markdown
146 lines
3.1 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**: 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
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 20.10.0+ (for Array.prototype.toSorted())
|
|
- NPM
|
|
- Running Home Assistant instance
|
|
- Home Assistant long-lived access token
|
|
|
|
### Basic Installation
|
|
|
|
```bash
|
|
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
|
cd homeassistant-mcp
|
|
npm install
|
|
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:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Usage Guide
|
|
|
|
### Device Discovery
|
|
```json
|
|
{
|
|
"tool": "list_devices"
|
|
}
|
|
```
|
|
|
|
### Basic Controls
|
|
```json
|
|
// Light control
|
|
{
|
|
"tool": "control",
|
|
"command": "turn_on",
|
|
"entity_id": "light.living_room",
|
|
"brightness": 128
|
|
}
|
|
|
|
// Climate control
|
|
{
|
|
"tool": "control",
|
|
"command": "set_temperature",
|
|
"entity_id": "climate.bedroom",
|
|
"temperature": 22
|
|
}
|
|
```
|
|
|
|
## 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
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm run dev # Development mode
|
|
npm run build # Build project
|
|
npm test # Run tests
|
|
```
|
|
|
|
## 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
|
|
|
|
## Project Status
|
|
|
|
✅ **Complete**
|
|
- Entity, Floor, and Area access
|
|
- Device control (Lights, Climate, Covers, Switches)
|
|
- Basic state management
|
|
|
|
🚧 **In Progress**
|
|
- Custom prompt testing
|
|
- Resource context integration
|
|
- Tool organization optimization
|
|
|
|
## 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)
|
|
|
|
## Contributing
|
|
|
|
1. Fork repository
|
|
2. Create feature branch
|
|
3. Submit pull request
|
|
|
|
## License
|
|
|
|
MIT License - See [LICENSE](LICENSE) file
|