MCP Home Assistant Server

A Model Context Protocol (MCP) server that allows Large Language Models (LLMs) like Claude to control your Home Assistant devices and smart home setup.

Features

• Device Control: Control lights, switches, climate devices, and more
• Device Discovery: Get lists of all devices or filter by type
• State Monitoring: Check current device states
• Docker Containerized: Runs in isolated Docker containers with auto-cleanup
• Secure Configuration: All credentials stored in environment variables
• Clean Integration: Optimized logging prevents error messages in Claude Desktop
• On-Demand Architecture: Containers spawn only when needed, auto-remove when done

Prerequisites

• Docker and Docker Compose installed
• Home Assistant instance running (yours is at 192.168.200.111:8123)
• Long-Lived Access Token from Home Assistant

Setup

1. Get Home Assistant Access Token

1. Go to your Home Assistant instance: http://192.168.200.111:8123
2. Navigate to Profile (bottom left menu)
3. Scroll down to Long-Lived Access Tokens
4. Click Create Token
5. Give it a name like "MCP Server"
6. Copy the generated token

2. Configure Environment Variables

1. Copy the example environment file:

   cp env_example.txt .env
   

2. Edit the .env file and replace your_long_lived_access_token_here with your actual token:

   HOME_ASSISTANT_TOKEN=your_actual_token_here
   

3. Verify other settings:

   • HOME_ASSISTANT_URL should already be set to your instance
   • VERIFY_SSL should be true unless you're using self-signed certificates

3. Build the Docker Image

# Build the Docker image
docker-compose build

# Test the image (optional)
echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1}' | docker run --rm -i --env-file .env mcp-homeassistant-mcp-homeassistant

Note: You don't need to run containers manually - Claude Desktop will manage them automatically!

Available Tools

The MCP server provides the following tools that LLMs can use:

Device Discovery

• get_all_devices: Get a list of all devices and their current states
• get_devices_by_type: Get devices of a specific type (light, switch, climate, etc.)
• get_device_state: Get the current state of a specific device

Device Control

• control_light: Control lights (turn on/off, adjust brightness, color temperature)
• control_switch: Control switches (turn on/off/toggle)
• control_climate: Control climate devices (temperature, mode)

Usage with Claude

To use this MCP server with Claude Desktop:

1. Install Claude Desktop from https://claude.ai/download

2. Configure MCP in Claude Desktop:

   • Open Claude Desktop settings
   • Go to the MCP section
   • Add a new MCP server with these settings:

     {
       "mcpServers": {
         "home-assistant": {
           "command": "docker",
           "args": [
             "run",
             "--rm", 
             "-i",
             "--stop-timeout=5",
             "--env-file",
             "/path/to/your/MCP-HomeAssistant/.env",
             "mcp-homeassistant-mcp-homeassistant"
           ]
         }
       }
     }
     

   • Replace /path/to/your/MCP-HomeAssistant/.env with the full path to your .env file

3. Restart Claude Desktop

4. Test the integration by asking Claude to control your devices:

   • "Turn on the living room lights"
   • "What's the current temperature in the bedroom?"
   • "List all my smart switches"

Example Interactions

Here are some example conversations you can have with Claude:

User: Can you turn on the living room lights?
Claude: I'll help you turn on the living room lights. Let me check what lights are available first.

[Claude uses the get_devices_by_type tool to find lights]
[Claude uses the control_light tool to turn on the lights]

The living room lights have been turned on successfully!

User: What's the temperature in my house?
Claude: Let me check your climate devices to see the current temperatures.

[Claude uses the get_devices_by_type tool to find climate devices]

Based on your climate devices, here's the current status:
- Living Room: 72°F
- Bedroom: 70°F
- Kitchen: 74°F

Troubleshooting

Connection Issues

• Verify your Home Assistant URL is correct: http://192.168.200.111:8123
• Check that your access token is valid and not expired
• Ensure your Docker container can reach your Home Assistant instance

SSL Issues

If you're using self-signed certificates, set VERIFY_SSL=false in your .env file.

Docker Issues

• Make sure Docker is running: docker --version
• Test the image manually: docker run --rm -i --env-file .env mcp-homeassistant-mcp-homeassistant
• Rebuild if needed: docker-compose build --no-cache

MCP Integration Issues

• Verify the path to your .env file in the Claude Desktop configuration
• Restart Claude Desktop after configuration changes
• Check Docker Desktop for running containers (multiple containers during use is normal)

Multiple Container Issue

If you see many containers running:

• This is normal behavior - Claude Desktop spawns containers on-demand
• Containers auto-remove when conversations end (thanks to --rm flag)
• Use the cleanup script if needed: ./cleanup-containers.sh

JSON-RPC Errors

If you see error messages in Claude Desktop:

• Make sure you're using the latest version of the Docker image
• The logging has been optimized to prevent stdout interference
• Restart Claude Desktop to clear any cached issues

Security Notes

• Your .env file contains sensitive credentials - keep it secure
• The MCP server only has access to the Home Assistant API token you provide
• Consider restricting the token's permissions in Home Assistant if possible
• Never commit the .env file to version control

Container Management

Normal Operation

• Multiple containers during use is expected - Claude Desktop spawns containers on-demand
• Containers auto-cleanup when conversations end (via --rm flag)
• No manual management needed - the system handles container lifecycle

Manual Cleanup (if needed)

# Stop all MCP containers
./cleanup-containers.sh

# Or manually:
docker stop $(docker ps -q --filter "ancestor=mcp-homeassistant-mcp-homeassistant")
docker container prune -f

Viewing Logs

# View logs from running containers
docker logs <container-name>

# Or check the log file inside container
docker exec <container-name> cat /app/mcp_server.log

Development

To modify the MCP server:

1. Edit mcp_server.py
2. Rebuild the container: docker-compose build
3. Test: docker run --rm -i --env-file .env mcp-homeassistant-mcp-homeassistant
4. Restart Claude Desktop to use the new image

License

This project is open source. Feel free to modify and distribute.