gilberth/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

📖

🚧 Smithery Deployment Status: Currently optimizing tool loading to prevent timeout during Smithery's tool scanning. See 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 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

Automation Tools

History Tools

Device Control Tools

System Tools

📝 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 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 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 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