Enhanced Homeassistant MCP
Enhanced MCP server for Home Assistant with comprehensive API integration - includes entity discovery, automation management, advanced services, system monitoring, and more
Installation
npx enhanced-homeassistant-mcpAsk AI about Enhanced Homeassistant MCP
Powered by Claude ยท Grounded in docs
I know everything about Enhanced Homeassistant MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Enhanced Home Assistant MCP
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:
# 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 โ
๐ง Smithery Deployment Status: Currently optimizing tool loading to prevent timeout during Smithery's tool scanning. See 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
# 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:
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
- Open Home Assistant in your browser
- Go to your Profile (click on your username in the sidebar)
- Scroll down to "Long-Lived Access Tokens"
- Click "Create Token"
- Give it a name and copy the generated token
Running the Server
Option 1: NPX (Recommended - No installation)
# 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
# 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:
# 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 para instrucciones detalladas.
โ๏ธ Smithery Deployment (Cloud)
Para usar el servidor desplegado en la nube a travรฉs de Smithery:
- Visita: Smithery.ai
- Busca:
@gilberth/enhanced-homeassistant-mcp - Configura tu instancia con:
- Home Assistant URL
- Long-lived access token
- Opciones opcionales (debug, timeout)
// 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
// 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
// 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
// Set thermostat temperature
const climate = await homeassistant_control_climate({
entity_id: "climate.living_room",
temperature: 22,
hvac_mode: "heat",
});
System Information
// 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/ directory:
๐ Available Examples
simple-client.js- Basic connection and tool usagesmithery-client.js- Full-featured demonstrationsecure-client.js- Environment-based secure configuration
๐ Quick Start with Examples
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
๐ Detailed Guide: See 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
- Create a new function in the appropriate tool file
- Register it with the server using
server.tool() - Follow the existing patterns for error handling and response formatting
- Add documentation to the README
Testing
# 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_entitiesto 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_servicesto 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:
DEBUG=true
๐ค Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - 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. 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 file for details.
๐ Acknowledgments
- Home Assistant - The amazing smart home platform
- Model Context Protocol - Protocol specification
- TypeScript - Language and tooling
๐ Support
If you encounter issues or have questions:
- Check the troubleshooting section
- Search existing GitHub issues
- 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
