Enhanced Homeassistant MCP

🚀 Enhanced Home Assistant MCP

The Enhanced Home Assistant MCP is a comprehensive MCP (Model Context Protocol) server. It offers extensive integration with Home Assistant, allowing AI assistants to interact with smart home devices, manage automations, and handle system - related tasks.

🚀 Quick Start

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 →

⚠️ Important Note

Smithery Deployment Status: Currently optimizing tool loading to prevent timeout during Smithery's tool scanning. See TIMEOUT_RESOLUTION.md for details.

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 (Recommended)

For an easy and secure deployment using Docker:

# Build the image
docker build -t enhanced-homeassistant-mcp .

# Run the container
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

📖 Complete Docker Guide: See DOCKER.md for detailed instructions.

☁️ Smithery Deployment (Cloud)

To use the server deployed in the cloud via Smithery:

1. Visit: Smithery.ai
2. Search: @gilberth/enhanced-homeassistant-mcp
3. Configure your instance with:
   • Home Assistant URL
   • Long - lived access token
   • Optional options (debug, timeout)

// Use with 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" }
);

🎯 Advantages of Smithery: No infrastructure configuration, automatic scaling, and global access.

✨ 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

🛠️ 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

🔧 Technical Details

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

📄 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