MCP Server for Homey
Model Context Protocol (MCP) server for interacting with the Homey smart home platform.
Features
- Device Management: List and control all Homey devices 
- Capability Control: Set device capabilities (on/off, brightness, temperature, etc.) 
- Zone Management: List and organize zones 
- Flow Automation: List and trigger Homey Flows 
Prerequisites
- Node.js >= 18 
- A Homey Pro device with local API access 
- Homey API token and local IP address 
Getting Homey API Credentials
- Navigate to Settings → API Keys in the Homey Web App 
- Tap "New API Key" 
- Give it a name and select appropriate permissions 
- Copy the generated API token 
- Find your Homey's local IP address in Settings → General → Network 
Installation
Configuration
Create a .env file or set environment variables:
Usage
Running the Server
With Node.js
With Docker
Build the Docker image:
Run the container:
Or use docker-compose (create a docker-compose.yml):
Then run:
Claude Desktop Configuration
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Available Tools
list_devices
List all devices connected to Homey with their capabilities and status.
get_device
Get detailed information about a specific device.
Parameters:
- deviceId(string): The ID of the device
set_capability
Set a capability value for a device.
Parameters:
- deviceId(string): The ID of the device
- capability(string): The capability to set (e.g.,- onoff,- dim,- target_temperature)
- value(any): The value to set
Examples:
- Turn on a light: - { deviceId: "abc123", capability: "onoff", value: true }
- Set brightness: - { deviceId: "abc123", capability: "dim", value: 0.5 }
- Set temperature: - { deviceId: "abc123", capability: "target_temperature", value: 21 }
list_zones
List all zones in your Homey setup.
list_flows
List all available Flows.
trigger_flow
Trigger a specific Homey Flow.
Parameters:
- flowId(string): The ID of the flow to trigger
Development
Watch Mode
Lint
Fix Linting Errors
Project Structure
Common Device Capabilities
- onoff: Turn device on/off (boolean)
- dim: Brightness level (0-1)
- target_temperature: Target temperature (number)
- measure_temperature: Current temperature (read-only)
- measure_power: Power consumption (read-only)
- measure_humidity: Humidity level (read-only)
- volume_set: Volume level (0-1)
- speaker_playing: Playback state (boolean)
Troubleshooting
Connection Issues
- Verify your Homey's local IP address hasn't changed 
- Ensure the API token has sufficient permissions 
- Check that your device is on the same network as Homey 
Device Not Found
- Use - list_devicesto get the correct device ID
- Verify the device is available in the Homey app 
License
MIT
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables interaction with Homey smart home devices through natural language, allowing users to control devices, manage zones, and trigger automation flows.