README.md•15.4 kB
# Enhanced Home Assistant MCP
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://www.home-assistant.io/)
A comprehensive MCP (Model Context Protocol) server that provides extensive integration with Home Assistant, enabling AI assistants to interact with smart home devices, automations, and system management.
## 🚀 Quick Start with NPX
**No installation required!** Run directly with npx:
```bash
# Set your Home Assistant credentials
export HOMEASSISTANT_URL="http://your-ha-ip:8123"
export HOMEASSISTANT_TOKEN="your-long-lived-access-token"
# Start the server
npx @thelord/enhanced-homeassistant-mcp
```
📖 **[Complete NPX Usage Guide →](NPX_USAGE.md)**
> **🚧 Smithery Deployment Status**: Currently optimizing tool loading to prevent timeout during Smithery's tool scanning. See [TIMEOUT_RESOLUTION.md](TIMEOUT_RESOLUTION.md) for details.
## 🎆 Features
### 📊 Basic Operations
- ✅ API status verification
- 📱 Entity state management
- 🔄 Service calls with advanced parameters
- 📝 Entity discovery and listing
- 🛠️ Configuration information
### 🤖 Automation & Control
- 📜 Automation management (enable/disable/trigger)
- 🎬 Scene activation
- 📜 Script execution
- 🔘 Input boolean controls
- 📅 Scheduled automation insights
### 📊 History & Monitoring
- 📈 Entity history tracking
- 📝 Logbook entries
- ⚠️ Error log monitoring
- 📡 System events
- 🔍 Configuration validation
### 🏠 Device Control
- 💡 **Lights**: Brightness, color, temperature control
- 🌡️ **Climate**: Temperature, HVAC modes, presets
- 📺 **Media Players**: Play/pause, volume, media selection
- 🏠 **Covers**: Open/close, position control
- 📢 **Notifications**: Multi-service messaging
- 🔍 **Device Discovery**: Filter by type/domain
### ⚙️ System Administration
- 📊 System information and health
- 🏷️ Template rendering (Jinja2)
- 🏠 Area and device management
- 🔌 Integration monitoring
- 🔄 System restart capabilities
- 📱 Supervisor and add-on management
- 🔍 Entity search and discovery
## 🚀 Quick Start
### Prerequisites
- Node.js 18+
- Home Assistant instance with API access
- Long-lived access token from Home Assistant
### Installation
```bash
# Clone the repository
git clone https://github.com/gilberth/enhanced-homeassistant-mcp.git
cd enhanced-homeassistant-mcp
# Install dependencies
npm install
# Copy environment template
cp .env.example .env
```
### Configuration
Edit the `.env` file with your Home Assistant details:
```env
HOME_ASSISTANT_URL=http://homeassistant.local:8123
HOME_ASSISTANT_TOKEN=your_long_lived_access_token_here
DEBUG=false
REQUEST_TIMEOUT=10000
```
### Getting Your Access Token
1. Open Home Assistant in your browser
2. Go to your Profile (click on your username in the sidebar)
3. Scroll down to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Give it a name and copy the generated token
### Running the Server
#### Option 1: NPX (Recommended - No installation)
```bash
# Quick start
npx @thelord/enhanced-homeassistant-mcp
# With options
npx @thelord/enhanced-homeassistant-mcp --debug start
npx @thelord/enhanced-homeassistant-mcp inspect
npx @thelord/enhanced-homeassistant-mcp health
```
#### Option 2: Local Installation
```bash
# Development mode
npm run dev
# Production mode
npm run build
npm start
# With MCP Inspector (for testing)
npm run inspector
```
### 🐳 Docker Deployment (Recomendado)
Para un despliegue fácil y seguro usando Docker:
```bash
# Construir la imagen
docker build -t enhanced-homeassistant-mcp .
# Ejecutar el contenedor
docker run -d \
--name homeassistant-mcp \
--restart unless-stopped \
-e HOME_ASSISTANT_URL="http://your-hass-ip:8123" \
-e HOME_ASSISTANT_TOKEN="your_long_lived_token" \
enhanced-homeassistant-mcp
```
📖 **Guía completa de Docker**: Ver [DOCKER.md](DOCKER.md) para instrucciones detalladas.
### ☁️ Smithery Deployment (Cloud)
Para usar el servidor desplegado en la nube a través de Smithery:
1. **Visita**: [Smithery.ai](https://smithery.ai)
2. **Busca**: `@gilberth/enhanced-homeassistant-mcp`
3. **Configura** tu instancia con:
- Home Assistant URL
- Long-lived access token
- Opciones opcionales (debug, timeout)
```javascript
// Usar con Smithery SDK
import { createSmitheryUrl } from "@smithery/sdk";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const config = {
homeAssistantToken: "your_token",
homeAssistantUrl: "http://your-hass-ip:8123",
};
const serverUrl = createSmitheryUrl(
"https://server.smithery.ai/@gilberth/enhanced-homeassistant-mcp",
{ config, apiKey: "your-smithery-api-key" }
);
```
🎯 **Ventajas de Smithery**: Sin configuración de infraestructura, escalado automático, y acceso global.
## 🛠️ Available Tools
### Basic Tools
| Tool | Description | Parameters |
| --------------------------------- | ----------------------- | ------------------------------------------------ |
| `homeassistant_api_status` | Check API connectivity | None |
| `homeassistant_get_entity_state` | Get entity state | `entity_id` |
| `homeassistant_list_all_entities` | List all entities | `domain` (optional) |
| `homeassistant_call_service` | Call HA service | `domain`, `service`, `entity_id`, `service_data` |
| `homeassistant_list_services` | List available services | `domain` (optional) |
| `homeassistant_get_config` | Get HA configuration | None |
### Automation Tools
| Tool | Description | Parameters |
| ------------------------------------ | ------------------------- | --------------------- |
| `homeassistant_list_automations` | List all automations | None |
| `homeassistant_toggle_automation` | Enable/disable automation | `entity_id`, `action` |
| `homeassistant_trigger_automation` | Trigger automation | `entity_id` |
| `homeassistant_list_scenes` | List all scenes | None |
| `homeassistant_activate_scene` | Activate scene | `entity_id` |
| `homeassistant_list_scripts` | List all scripts | None |
| `homeassistant_run_script` | Run script | `entity_id` |
| `homeassistant_list_input_booleans` | List input booleans | None |
| `homeassistant_toggle_input_boolean` | Toggle input boolean | `entity_id`, `action` |
### History Tools
| Tool | Description | Parameters |
| ---------------------------------- | ---------------------- | --------------------------------------------------------- |
| `homeassistant_get_entity_history` | Get entity history | `entity_id`, `start_time`, `end_time`, `minimal_response` |
| `homeassistant_get_logbook` | Get logbook entries | `entity_id`, `start_time`, `end_time` |
| `homeassistant_get_events` | List event types | None |
| `homeassistant_get_error_log` | Get error log | None |
| `homeassistant_check_config` | Validate configuration | None |
### Device Control Tools
| Tool | Description | Parameters |
| ------------------------------------ | ----------------------- | -------------------------------------------------------------------- |
| `homeassistant_control_lights` | Control lights | `entity_id`, `action`, `brightness`, `color_name`, `rgb_color`, etc. |
| `homeassistant_control_climate` | Control climate devices | `entity_id`, `temperature`, `hvac_mode`, `preset_mode`, etc. |
| `homeassistant_control_media_player` | Control media players | `entity_id`, `action`, `media_content_id`, `volume_level`, etc. |
| `homeassistant_control_covers` | Control covers/blinds | `entity_id`, `action`, `position` |
| `homeassistant_get_devices_by_type` | List devices by domain | `domain` |
| `homeassistant_send_notification` | Send notifications | `service`, `title`, `message`, `target` |
### System Tools
| Tool | Description | Parameters |
| --------------------------------- | ---------------------- | ------------------ |
| `homeassistant_system_info` | Get system information | None |
| `homeassistant_render_template` | Render Jinja2 template | `template` |
| `homeassistant_list_areas` | List all areas | None |
| `homeassistant_list_devices` | List all devices | None |
| `homeassistant_list_integrations` | List integrations | None |
| `homeassistant_restart_service` | Restart Home Assistant | `confirm` |
| `homeassistant_supervisor_info` | Get Supervisor info | None |
| `homeassistant_list_addons` | List add-ons | None |
| `homeassistant_search_entities` | Search entities | `search`, `domain` |
## 📝 Usage Examples
### Basic Entity Control
```javascript
// Get light state
const lightState = await homeassistant_get_entity_state({
entity_id: "light.living_room",
});
// Turn on light with brightness and color
const result = await homeassistant_control_lights({
entity_id: "light.living_room",
action: "turn_on",
brightness_pct: 75,
color_name: "warm_white",
});
```
### Automation Management
```javascript
// List all automations
const automations = await homeassistant_list_automations();
// Enable an automation
const enabled = await homeassistant_toggle_automation({
entity_id: "automation.morning_routine",
action: "turn_on",
});
// Activate a scene
const scene = await homeassistant_activate_scene({
entity_id: "scene.movie_time",
});
```
### Climate Control
```javascript
// Set thermostat temperature
const climate = await homeassistant_control_climate({
entity_id: "climate.living_room",
temperature: 22,
hvac_mode: "heat",
});
```
### System Information
```javascript
// Get system overview
const systemInfo = await homeassistant_system_info();
// Search for entities
const searchResults = await homeassistant_search_entities({
search: "temperature",
domain: "sensor",
});
```
## 🎮 Client Examples
Ready-to-use client examples are available in the [`examples/`](examples/) directory:
### 📁 Available Examples
- **`simple-client.js`** - Basic connection and tool usage
- **`smithery-client.js`** - Full-featured demonstration
- **`secure-client.js`** - Environment-based secure configuration
### 🚀 Quick Start with Examples
```bash
cd examples
npm install
cp .env.example .env
# Edit .env with your credentials
npm run secure
```
🔗 **Using with Smithery**: The examples are ready for use with servers deployed on [Smithery.ai](https://smithery.ai)
📖 **Detailed Guide**: See [`examples/README.md`](examples/README.md) for complete setup instructions
## 🔧 Development
### Project Structure
```
src/
├── index.ts # Main server file
├── utils/
│ └── api.ts # API utilities
└── tools/
└── homeassistant/
├── basic.ts # Basic HA operations
├── automation.ts # Automation tools
├── history.ts # History and monitoring
├── devices.ts # Device control
└── system.ts # System administration
```
### Adding New Tools
1. Create a new function in the appropriate tool file
2. Register it with the server using `server.tool()`
3. Follow the existing patterns for error handling and response formatting
4. Add documentation to the README
### Testing
```bash
# Run with inspector for interactive testing
npm run inspector
# Test specific endpoints
curl -H "Authorization: Bearer YOUR_TOKEN" \
"http://localhost:8123/api/states"
```
## 🚑 Troubleshooting
### Common Issues
**Connection Failed**
- Verify HOME_ASSISTANT_URL is correct and accessible
- Check that Home Assistant is running
- Ensure no firewall blocking the connection
**Authentication Failed**
- Verify your long-lived access token is correct
- Check token hasn't expired or been revoked
- Ensure token has necessary permissions
**Entity Not Found**
- Use `homeassistant_list_all_entities` to find correct entity IDs
- Check entity exists and is enabled in Home Assistant
- Verify correct domain prefix (e.g., `light.`, `sensor.`)
**Service Call Failed**
- Use `homeassistant_list_services` to verify service availability
- Check service parameters are correct for your device
- Some services require specific entity types or states
### Debug Mode
Enable debug logging in your `.env`:
```env
DEBUG=true
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open a Pull Request
### Development Guidelines
- Follow existing code style and patterns
- Add proper TypeScript types
- Include error handling for all API calls
- Update documentation for new features
- Test with real Home Assistant instance
## 📜 API Reference
This MCP server uses the [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/). Key endpoints:
- `/api/` - API information
- `/api/states` - Entity states
- `/api/services` - Available services
- `/api/config` - Configuration
- `/api/history` - Historical data
- `/api/logbook` - Logbook entries
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Home Assistant](https://www.home-assistant.io/) - The amazing smart home platform
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification
- [TypeScript](https://www.typescriptlang.org/) - Language and tooling
## 📞 Support
If you encounter issues or have questions:
1. Check the [troubleshooting section](#-troubleshooting)
2. Search existing [GitHub issues](https://github.com/gilberth/enhanced-homeassistant-mcp/issues)
3. Create a new issue with:
- Home Assistant version
- MCP server logs
- Steps to reproduce
- Expected vs actual behavior
---
**Made with ❤️ for the Home Assistant community**