Homey MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Homey MCP Server turn on living room lights"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Homey MCP Server
This is an MCP server for Homey (by Athom) that allows AI agents to control smart home devices, trigger flows, and query zones.
Prerequisites
Homey Pro or Homey Cloud
Homey Personal Access Token (API Key). You can create one in the Homey Web App under
Settings → API Keys.
Related MCP server: MCP Server for Homey API
Installation
Clone or copy this directory.
Run
npm install.Create a
.envfile based on.env.example:HOMEY_TOKEN=your_token_here
Usage
Connecting with Claude Desktop
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"homey": {
"command": "node",
"args": ["/Users/XX/.gemini/antigravity/scratch/homey-mcp/index.js"],
"env": {
"HOMEY_TOKEN": "YOUR_TOKEN_HERE"
}
}
}
}Connecting with ChatGPT Desktop
ChatGPT (macOS/Windows) supports MCP servers via Developer Mode.
Open ChatGPT Desktop.
Go to Settings → Apps → Advanced settings.
Enable Developer Mode.
Click Create app (or "Add App") and configure a connection:
Name: Homey
URL:
http://localhost:3000(if running locally as an HTTP/SSE server) or use the Claude-style local command if supported in your version.
NOTEChatGPT currently primarily supports MCP overSSE (HTTP). To use this as a local command-line tool like in Claude, you may need a bridge or for ChatGPT to fully roll out stdio support.
Connecting with ChatGPT (Web/Custom GPTs)
To use Homey MCP in the ChatGPT web interface:
You must host this MCP server on a public URL (e.g., via
ngrokor a VPS).Use the Actions feature in a Custom GPT to connect to your MCP server's OpenAPI spec or SSE endpoint.
Available Tools (19 Total)
🏠 Devices & Control
homey_list_devices: List all devices with their current states (ID, Name, Zone, Class, Capabilities).homey_get_device: Get full details for a single device by its ID.homey_get_sensor_readings: Get current readings from all sensors (temperature, humidity, motion, etc.) across the home.homey_find_devices_by_zone: List all devices in a specific room or floor.homey_control_lights_in_zone: Bulk control for all lights in a specific zone (Turn on/off).homey_set_capability: Set a specific capability value (e.g.,onoff,dim,target_temperature).
🚀 Flows & Automation
homey_list_flows: List all standard flows.homey_list_advanced_flows: List all Advanced Flows.homey_run_flow: Trigger a standard flow by its ID.homey_run_advanced_flow: Trigger an Advanced Flow by its ID.homey_get_flow: Get full configuration details for a specific flow.homey_get_flow_folders: List the folder structure used to organize flows.
📍 Zones
homey_list_zones: List all zones (rooms/floors) and their hierarchy.
🧠 Logic & Flow Cards
homey_get_flow_cards: List available flow cards (triggers, conditions, actions) on the system.homey_run_flow_card_action: Execute a specific flow card action directly without needing a flow.homey_get_device_flow_capabilities: Identify which flow cards are applicable to a specific device.
📊 Data & Insights
homey_get_energy_data: Discover and list available energy/power logs.homey_get_device_insights: Fetch historical data logs for any device capability over a period (today,last7days, etc.).homey_get_live_insights: Access real-time dashboard data for device capabilities.
Troubleshooting
"HomeyAPI.createCloudAPI is not a function"
This usually happens if the Personal Access Token is used without a HOMEY_IP. Ensure you provide HOMEY_IP for Homey Pro local connections. For Homey Cloud, Ensure your token is valid and specifically created for the Web API.
Connection Closed / MCP Error
If the server fails to connect to Homey, it will now start gracefully but return an error message when you try to use a tool. Check the console logs (stderr) for the specific connection error.
Environment Variables
If running via Claude Desktop, ensure the env section in your config contains the correct HOMEY_TOKEN and optionally HOMEY_IP.
Available Tools
19 toolshomey_control_lights_in_zoneB
Turn all lights in a specific zone on or off.
Inputs: on (required), zoneName (required).
homey_find_devices_by_zoneA
List all devices in a specific zone (room or floor).
Inputs: zoneId, zoneName.
homey_get_deviceA
Get detailed information about a specific device by ID.
Inputs: id (required).
homey_get_device_flow_capabilitiesB
Identify which flow cards are applicable to a specific device.
Inputs: deviceId (required).
homey_get_device_insightsA
Retrieve historical logs for any device capability over a period.
Inputs: logId (required), resolution.
homey_get_energy_dataB
Get energy consumption logs for devices.
Inputs: deviceId.
homey_get_flowB
Get detailed information about a specific flow.
Inputs: id (required).
homey_get_flow_cardsA
List available flow cards (triggers, conditions, actions) for devices or system.
Inputs: type.
homey_get_flow_foldersA
List the folder structure for flows.
Inputs: no named parameters.
homey_get_live_insightsC
Provides real-time data for specific device capabilities (Dashboard style).
Inputs: deviceId (required), capabilityId.
homey_get_sensor_readingsA
Get current readings from all sensors (temperature, humidity, motion, etc.) across the home.
Inputs: no named parameters.
homey_list_advanced_flowsB
List all Advanced Flows on Homey.
Inputs: no named parameters.
homey_list_devicesA
List all devices on Homey with their current states.
Inputs: no named parameters.
homey_list_flowsA
List all standard flows on Homey.
Inputs: no named parameters.
homey_list_zonesA
List all zones (rooms/floors) and their hierarchy.
Inputs: no named parameters.
homey_run_advanced_flowB
Trigger a specific Advanced Flow.
Inputs: id (required).
homey_run_flowB
Trigger a specific standard flow.
Inputs: id (required).
homey_run_flow_card_actionC
Manually execute a specific flow card action.
Inputs: id (required), uri (required), args.
homey_set_capabilityA
Set a capability value on a device (e.g. turn on/off, dim, target_temperature).
Inputs: value (required), deviceId (required), capabilityId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a distinct resource/action (devices, sensors, zones, flows, energy, insights). Even similar tools like list_flows vs list_advanced_flows are clearly differentiated by type. No overlapping purposes that would cause misselection.
All tools follow the consistent 'homey_verb_noun' pattern with snake_case. Verbs like list, get, find, control, set, run are used predictably. The naming convention is uniform and easy to infer.
19 tools is slightly above the typical well-scoped range, but the broad scope of a smart home hub (devices, zones, flows, energy, insights) justifies the count. Each tool serves a distinct purpose, so it doesn't feel excessive.
The tool surface covers core home automation workflows: reading device/sensor state, controlling devices, managing/running flows, and accessing energy/insight data. Minor gaps exist (e.g., no create/update/delete for flows or zones, no bulk zone control beyond lights), but these are workable and typical for a control-oriented server.
Maintenance
Related MCP Connectors
Home energy for AI assistants: live Power flow, Energy history, solar forecast, and device control.
Control and query Heiman smart home devices: lights, AC, curtains, climate, logs and scenes.
1Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Build and run agents and automations across hundreds of apps using natural language.
Related MCP Servers
- FlicenseBqualityNot gradedmaintenanceEnables interaction with Homey smart home devices through natural language, allowing users to control devices, manage zones, and trigger automation flows.64-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with Homey home automation systems for managing flows, devices, and zones. Perfect for bulk automation tasks like batch renaming flows, organizing them into folders, and managing devices across zones through natural language.-
- AlicenseNot gradedqualityDmaintenanceEnables Claude AI to control and manage Homey Pro smart home devices, flows, and analytics through natural language.12MIT
- AlicenseAqualityBmaintenanceEnables natural language control of Homey Pro smart home systems, including devices, flows, zones, energy monitoring, weather, alarms, and system management, with 43 tools and troubleshooting prompts.5021 npmMIT