Home Assistant MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating with Home Assistant. This server provides 60 tools and resources to interact with your Home Assistant instance via the REST API, enabling full smart home management and automation.

🚀 Features Overview

60 Total Tools across 9 Major Categories for comprehensive Home Assistant management:

🔧 Core Operations (13 tools)

Entity State Management: Get, set, update, and delete entity states
Service Calls: Execute Home Assistant services with full response support
Entity Search: Advanced search with filtering by name, domain, or state
Event Handling: Fire custom events with data payloads
Template Rendering: Render Home Assistant templates with live data

🏠 Area & Device Management (8 tools)

Area Management: Create, update, delete areas/zones with aliases
Device Registry: List, configure, and manage all Home Assistant devices
Entity Organization: Assign entities to areas, bulk area operations
Device Assignment: Move devices between areas, enable/disable devices

🖥️ System Management (6 tools)

System Control: Restart/stop Home Assistant safely
Health Monitoring: Check system health and component status
Configuration Validation: Validate configs before applying changes
Supervisor Integration: Get supervisor info (Home Assistant OS)

🔌 Integration Management (6 tools)

Integration Lifecycle: List, enable, disable, delete integrations
Integration Troubleshooting: Reload integrations, get detailed info
Dynamic Management: Programmatically manage integration configurations

🔔 Notification Services (3 tools)

Multi-Channel Notifications: Send via mobile apps, persistent notifications
Service Discovery: List all available notification services
Notification Management: Dismiss persistent notifications

📋 Entity Registry Management (4 tools)

Entity Configuration: Update entity names, areas, enabled/disabled status
Bulk Operations: Enable/disable multiple entities
Registry Information: Get detailed entity registry data

🤖 Automation & Scene Management (12 tools)

Automation Control: Create, update, delete, trigger automations
Scene Management: Activate scenes, create new scenes from current states
Automation Debugging: Get execution traces and troubleshooting data
Lifecycle Management: Full CRUD operations for automations

📊 Data & History (4 tools)

Historical Data: Advanced history queries with filtering options
Logbook Access: Get event history and entity changes
Error Logs: Retrieve Home Assistant error logs for debugging

🎥 Calendar & Media (4 tools)

Calendar Integration: List calendars and get events with date ranges
Camera Support: Get images from camera entities (base64 encoded)
Intent Processing: Handle Home Assistant voice/text intents
Real-time Events: Subscribe to live Home Assistant events via SSE

Installation

Clone this repository:

git clone https://github.com/cronus42/homeassistant-mcp.git
cd homeassistant-mcp

Run the setup script:

./setup.sh

Get your Home Assistant Long-Lived Access Token:
- Log into your Home Assistant web interface
- Go to Profile (click on your user name in bottom left)
- Scroll down to "Long-lived access tokens"
- Click "Create Token"
- Give it a name (e.g., "MCP Server")
- Copy the token
Configure your settings:

cp .env.example .env
# Edit .env with your Home Assistant URL and token

Test the connection:

python tests/test_connection.py

Usage with MCP Clients

Warp Terminal Integration

Run the setup script:

./setup.sh

Configure Warp to use the MCP server:

warp mcp add-server --config mcp_config.json

Or manually start the server:

./start_server.sh

Claude Desktop Configuration

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "homeassistant": {
      "command": "/path/to/homeassistant-mcp/start_server.sh",
      "env": {},
      "args": []
    }
  }
}

Available Tools

`get_entity_state`

Get the current state of a specific Home Assistant entity.

{
  "entity_id": "light.living_room"
}

`call_service`

Call a Home Assistant service to control devices.

{
  "domain": "light",
  "service": "turn_on",
  "entity_id": "light.living_room",
  "service_data": {
    "brightness": 255,
    "color_temp": 3000
  }
}

`search_entities`

Search for entities by name, domain, or state.

{
  "query": "temperature",
  "domain": "sensor"
}

`fire_event`

Fire a custom event in Home Assistant.

{
  "event_type": "custom_automation_trigger",
  "event_data": {
    "source": "mcp_server",
    "action": "test"
  }
}

`get_history`

Get historical data for specific entities.

{
  "entity_ids": ["sensor.temperature", "light.living_room"],
  "start_time": "2024-01-01T00:00:00Z"
}

New Feature Examples

Area Management

{
  "tool": "get_areas",
  "arguments": {}
}

Create and Manage Areas

{
  "tool": "create_area",
  "arguments": {
    "name": "Home Office",
    "aliases": ["office", "workspace"]
  }
}

Device Management

{
  "tool": "get_devices",
  "arguments": {}
}

System Health Check

{
  "tool": "get_system_health",
  "arguments": {}
}

Send Notifications

{
  "tool": "send_notification",
  "arguments": {
    "message": "Security Alert: Front door opened",
    "title": "Security System",
    "target": "mobile_app_phone"
  }
}

Integration Management

{
  "tool": "get_integrations",
  "arguments": {}
}

Testing

The server includes comprehensive test suites:

Run All Tests

# Test tool definitions and schemas
python tests/test_mcp_tools.py

# Test tool handlers with mocking
python tests/test_tool_handlers.py

# Test with real Home Assistant (requires HA_TOKEN)
python tests/test_new_features.py

# Test basic connection
python tests/test_connection.py

Test Results

✅ 60/60 tools properly defined
✅ All schemas validated
✅ All tool handlers working correctly
✅ 100% test coverage for new features

Available Resources

homeassistant://states - Current state of all entities
homeassistant://config - Home Assistant configuration
homeassistant://services - Available services
homeassistant://events - Available event types

Usage Examples

Turn on a light

{
  "tool": "call_service",
  "arguments": {
    "domain": "light",
    "service": "turn_on",
    "entity_id": "light.living_room"
  }
}

Check temperature sensors

{
  "tool": "search_entities",
  "arguments": {
    "query": "temperature",
    "domain": "sensor"
  }
}

Get current state of all lights

{
  "tool": "search_entities",
  "arguments": {
    "query": "light",
    "domain": "light"
  }
}

Security

Store your Home Assistant token securely
Use environment variables for configuration
Consider network security between your MCP client and Home Assistant
Limit token permissions if possible

Troubleshooting

Connection Issues

Verify Home Assistant URL is accessible
Check if Home Assistant API is enabled
Ensure token is valid and has proper permissions

Authentication Errors

Regenerate long-lived access token
Check token format (should be a long string)
Verify token is set in environment variable

Service Call Failures

Check entity IDs exist in Home Assistant
Verify service names and parameters
Check Home Assistant logs for errors

Contributing

Feel free to submit issues and enhancement requests!

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A comprehensive Model Context Protocol server providing 60 tools across 9 categories to interact with and manage Home Assistant smart home systems via the REST API.

Related MCP Servers

Home Assistant MCP Server
hekmon8
A
security
A
license
A
quality
A server that enables interaction with Home Assistant devices and automations through the Model Context Protocol, allowing users to monitor device states, control devices, trigger automations, and list entities.
Last updated -
4
43
JavaScript
MIT License
MCP Personal Assistant Agent
zhangzhongnan928
-
security
F
license
-
quality
A versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
13
Python
Home Assistant MCP Server
miguelg719
-
security
A
license
-
quality
A Model Context Protocol server that integrates with Home Assistant to provide smart home control capabilities through natural language, supporting devices like lights, climate systems, locks, alarms, and humidifiers.
Last updated -
2
Python
MIT License
MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
16
1
TypeScript

View all related MCP servers