enhanced-homeassistant-mcp

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

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)

# 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:

1. Visita: Smithery.ai
2. Busca: @gilberth/enhanced-homeassistant-mcp
3. 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 usage
• smithery-client.js - Full-featured demonstration
• secure-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

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

# 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:

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. 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:

1. Check the troubleshooting section
2. Search existing GitHub 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