Content
# Homey MCP Server
A comprehensive Model Context Protocol (MCP) server for Homey smart home automation systems, providing seamless integration with Claude AI assistants.
## 🏠 Overview
The Homey MCP Server enables Claude AI to interact directly with your Homey Pro smart home system, offering real-time device control, automation management, and advanced analytics through natural language conversations.
**Key Capabilities:**
- 📱 **Device Control**: Control lights, thermostats, sensors, and smart appliances
- 🔄 **Flow Management**: Trigger and manage Homey automation flows
- 📊 **Advanced Analytics**: Historical data analysis, energy monitoring, and usage patterns
- 🌡️ **Climate Intelligence**: Temperature and humidity monitoring across zones
- ⚡ **Energy Insights**: Power consumption tracking and optimization recommendations
- 📈 **Live Monitoring**: Real-time dashboard metrics and system status
## 🚀 Quick Start
### Prerequisites
- Homey Pro device with local API access enabled
- Python 3.11+ with uv package manager
- Claude Desktop application
- Valid Homey Personal Access Token
**Platform Support**: macOS, Windows, Linux
### Installation
1. **Clone and Setup**
```bash
git clone <repository-url>
cd mcp-homey
make install
# Make the script executable (macOS/Linux only)
chmod +x start_homey_mcp.sh
```
2. **Get Homey Token**
- Navigate to [Homey Developer Portal](https://my.homey.app)
- Go to **Settings → Advanced → API Keys**
- Create new API Key with **all available scopes**
3. **Configure Claude Desktop**
**⚠️ IMPORTANT: Replace all paths with YOUR actual paths**
### 🍎 **macOS/Linux**
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"homey": {
"command": "/path/to/your/uv/binary",
"args": ["run", "--directory", "/path/to/your/mcp-homey", "python", "src/homey_mcp/__main__.py"],
"env": {
"HOMEY_LOCAL_ADDRESS": "YOUR_HOMEY_IP_ADDRESS",
"HOMEY_LOCAL_TOKEN": "your-token-here",
"OFFLINE_MODE": "false",
"DEMO_MODE": "false"
}
}
}
}
```
**Find your uv path with:**
```bash
which uv
# Usually: /Users/yourname/.local/bin/uv
# or: /usr/local/bin/uv
# or: /opt/homebrew/bin/uv
```
**Example with real paths:**
```json
{
"mcpServers": {
"homey": {
"command": "/Users/yourname/.local/bin/uv",
"args": ["run", "--directory", "/Users/yourname/Projects/mcp-homey", "python", "src/homey_mcp/__main__.py"],
"env": {
"HOMEY_LOCAL_ADDRESS": "YOUR_HOMEY_IP_ADDRESS",
"HOMEY_LOCAL_TOKEN": "your-personal-access-token",
"OFFLINE_MODE": "false",
"DEMO_MODE": "false"
}
}
}
}
```
### 🪟 **Windows**
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"homey": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\mcp-homey", "python", "src/homey_mcp/__main__.py"],
"env": {
"HOMEY_LOCAL_ADDRESS": "YOUR_HOMEY_IP_ADDRESS",
"HOMEY_LOCAL_TOKEN": "your-token-here",
"OFFLINE_MODE": "false",
"DEMO_MODE": "false"
}
}
}
}
```
**Find your uv path with:**
```powershell
where uv
# Usually: C:\Users\yourname\.local\bin\uv.exe
# or: C:\Program Files\uv\uv.exe
```
**Example with real paths:**
```json
{
"mcpServers": {
"homey": {
"command": "C:\\Users\\yourname\\.local\\bin\\uv.exe",
"args": ["run", "--directory", "C:\\Users\\yourname\\Projects\\mcp-homey", "python", "src/homey_mcp/__main__.py"],
"env": {
"HOMEY_LOCAL_ADDRESS": "YOUR_HOMEY_IP_ADDRESS",
"HOMEY_LOCAL_TOKEN": "your-personal-access-token",
"OFFLINE_MODE": "false",
"DEMO_MODE": "false"
}
}
}
}
```
**Windows Notes:**
- Install uv first: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
- Use full Windows paths with double backslashes: `C:\\Users\\Name\\Projects\\mcp-homey`
- Restart PowerShell after installing uv
- Use `where uv` to find the exact uv.exe path
4. **Find Your Paths**
Before configuring Claude, find the correct paths for your system:
**macOS/Linux:**
```bash
# Find uv location
which uv
# Find project directory
cd path/to/mcp-homey && pwd
# Example output:
# /Users/yourname/.local/bin/uv
# /Users/yourname/Projects/mcp-homey
```
**Windows:**
```powershell
# Find uv location
where uv
# Find project directory
cd path\to\mcp-homey; pwd
# Example output:
# C:\Users\yourname\.local\bin\uv.exe
# C:\Users\yourname\Projects\mcp-homey
```
5. **Restart Claude Desktop and test!**
## ⚙️ Operating Modes
Switch modes by editing your Claude Desktop config and restarting Claude:
### 🏠 **Normal Mode** (Real Homey)
```json
"env": {
"HOMEY_LOCAL_ADDRESS": "YOUR_HOMEY_IP_ADDRESS",
"HOMEY_LOCAL_TOKEN": "your-actual-token",
"OFFLINE_MODE": "false",
"DEMO_MODE": "false"
}
```
### 🧪 **Demo Mode** (Testing without Homey)
```json
"env": {
"OFFLINE_MODE": "true",
"DEMO_MODE": "true"
}
```
*Demo includes: Multi-room setup, various device types, sensors, flows, and analytics data*
### 🔧 **Development Mode**
```json
"env": {
"OFFLINE_MODE": "true",
"DEMO_MODE": "false"
}
```
*Offline but minimal demo data*
## 🛠️ Available Tools (17 total)
### 📱 Device Control (7 tools)
`get_devices` • `control_device` • `get_device_status` • `get_zones` • `find_devices_by_zone` • `control_lights_in_zone` • `get_sensor_readings`
### 🔄 Flow Management (7 tools)
`get_flows` • `get_flow` • `trigger_flow` • `get_device_flow_capabilities` • `get_flow_folders` • `get_flow_cards` • `run_flow_card_action`
### 📊 Insights & Analytics (3 tools)
`get_device_insights` • `get_energy_data` • `get_live_insights`
## 💬 Usage Examples
```
"What devices do I have?"
"What zones are available?"
"Turn on the kitchen lights at 75%"
"Set thermostat to 22 degrees"
"Start the evening routine"
"Show my energy usage this month"
"Export temperature data to CSV"
```
## 🔧 Development & Debugging
### 🍎 **macOS/Linux**
```bash
# Manual testing
export OFFLINE_MODE="true" DEMO_MODE="true"
./start_homey_mcp.sh
# Development commands
make install test lint format
python test_capabilities.py
python test_insights.py
# Debugging
tail -f homey_mcp_debug.log
make inspector # Web UI at localhost:5173
```
### 🪟 **Windows**
```powershell
# Manual testing
$env:OFFLINE_MODE="true"; $env:DEMO_MODE="true"
uv run python src/homey_mcp/__main__.py
# Development commands
uv sync
uv run pytest
uv run python test_capabilities.py
uv run python test_insights.py
# Debugging
Get-Content homey_mcp_debug.log -Wait # Like tail -f
```
## 🔍 Troubleshooting
### 🪟 **Windows-specific**
**❌ "uv not found"** → Install uv: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
**❌ Path issues** → Use full Windows paths with double backslashes: `C:\\Users\\Name\\Projects\\mcp-homey`
**❌ PowerShell execution policy** → Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
**❌ Wrong uv path** → Use `where uv` to find exact path, then use full path like `C:\\Users\\yourname\\.local\\bin\\uv.exe`
### 🍎 **macOS/Linux**
**❌ "uv not found"** → Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh` and restart terminal
**❌ "command not found"** → Use full path to uv binary: `/Users/yourname/.local/bin/uv`
**❌ Permission denied** → Make sure uv is executable: `chmod +x /path/to/uv`
**❌ Wrong paths** → Use `which uv` and `pwd` to get correct absolute paths
### 🌐 **All Platforms**
**❌ Missing scopes** → Create API key with ALL scopes at [my.homey.app](https://my.homey.app)
**❌ Connection timeout** → Verify Homey IP and network connectivity
**❌ Unauthorized** → Check token validity and expiration
---
**Built with ❤️ for the Homey community**
