Home Assistant MCP Server Integration

This workspace provides GitHub Copilot integration with Home Assistant through the Model Context Protocol (MCP), enabling natural language control and monitoring of your smart home devices.

🚀 Features

• Natural Language Control: Control lights, switches, and devices using conversational commands
• Real-time Monitoring: Query device states, sensors, and areas
• Media Control: Manage media players (play/pause, volume, search)
• List Management: Interact with your Shopping List and to-do items
• Custom Prompts: Pre-built prompt library for common tasks

📋 Prerequisites

• Home Assistant instance with MCP server integration installed
• GitHub Copilot subscription
• VS Code with GitHub Copilot extension

✅ Tested Installation

This integration has been tested with the following Home Assistant configuration:

• Installation Method: Home Assistant OS
• Core: 2026.2.2
• Supervisor: 2026.02.2
• Operating System: 17.1
• Frontend: 20260128.6

⚙️ Setup

1. Environment Variables

Set the following environment variables for your Home Assistant connection:

# Windows (PowerShell)
$env:HOME_ASSISTANT_DOMAIN = "your-homeassistant-domain.com:8123"
$env:HOME_ASSISTANT_TOKEN = "your-long-lived-access-token"

# Linux/macOS
export HOME_ASSISTANT_DOMAIN="your-homeassistant-domain.com:8123"
export HOME_ASSISTANT_TOKEN="your-long-lived-access-token"

Get your Long-Lived Access Token:

1. Open Home Assistant
2. Go to your Profile (click your name in the sidebar)
3. Scroll to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Copy the generated token

2. MCP Configuration

The MCP server is configured in .vscode/mcp.json:

{
    "servers": {
        "home-assistant-mcp": {
            "type": "http",
            "url": "http://${env:HOME_ASSISTANT_DOMAIN}/mcp_server/sse",
            "headers": {
                "Authorization": "Bearer ${env:HOME_ASSISTANT_TOKEN}"
            }
        }
    }
}

3. Restart VS Code

After setting environment variables, restart VS Code to load the configuration.

🎯 Usage

Using Prompts

Prompts are located in .github/prompts and can be executed through GitHub Copilot Chat:

1. Command Palette: Ctrl+Shift+P → "GitHub Copilot: Run Prompt"
2. Chat Panel: Ctrl+Alt+I → Type # and select a prompt
3. File Context: Attach prompt files with #file: in chat

Available Prompts

• areas.prompt.md: List all Home Assistant areas with emojis
• devices_by_area.prompt.md: Show devices in Living Room

Natural Commands

You can also use natural language directly in Copilot Chat:

- "Turn on the kitchen lights"
- "Set living room brightness to 50%"
- "What's the temperature in the living room?"
- "Show me all my areas"
- "Add milk to my shopping list"
- "Turn off all lights"

🛠️ Available MCP Tools

Device Control

• HassTurnOn / HassTurnOff - Control lights, switches, outlets, locks, covers
• HassLightSet - Set brightness, color, and temperature for lights

Media Player

• HassMediaPause / HassMediaUnpause - Pause/resume playback
• HassMediaNext / HassMediaPrevious - Skip tracks
• HassMediaSearchAndPlay - Search and play media
• HassMediaPlayerMute / HassMediaPlayerUnmute - Mute control
• HassSetVolume / HassSetVolumeRelative - Volume control

Lists & To-Do

• todo_get_items - Query Shopping List
• HassListAddItem - Add items to lists
• HassListCompleteItem - Mark items complete

Information

• GetLiveContext - Get real-time device states, sensors, and areas
• GetDateTime - Current date and time

Other

• HassCancelAllTimers - Cancel all active timers

📝 Creating Custom Prompts

Create new prompts in .github/prompts:

---
agent: 'agent'
tools: ['home-assistant-mcp/GetLiveContext', 'home-assistant-mcp/HassTurnOn']
description: 'Brief description of the prompt'
---

Your prompt instructions here. Be specific about what you want.

Important: Always prefix tools with home-assistant-mcp/ (e.g., home-assistant-mcp/HassTurnOn)

🏠 Your Home Setup

Areas:

• Master Bedroom
• Hallway
• Guest Bedroom
• Living Room
• Kitchen
• Landing
• Porch

Device Types:

• Lights (including WLED strips)
• Temperature & Humidity Sensors
• Media Players
• Switches
• Shopping List

🤝 Contributing

Add new prompts by creating .prompt.md files in .github/prompts. Follow the existing format and always use the full tool names with home-assistant-mcp/ prefix.

📚 Resources

• Home Assistant MCP Server Integration Documentation
• Home Assistant MCP Server
• Model Context Protocol
• GitHub Copilot Documentation

🔒 Security

• Never commit your access tokens to version control
• Use environment variables for sensitive configuration
• Ensure your Home Assistant instance is secured with HTTPS in production
• Regularly rotate your long-lived access tokens

Happy Automating! 🎉