Skip to main content
Glama
Homey MCP Server

Homey MCP Server

by decline27

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

  1. Clone or copy this directory.

  2. Run npm install.

  3. Create a .env file 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.

  1. Open ChatGPT Desktop.

  2. Go to Settings → Apps → Advanced settings.

  3. Enable Developer Mode.

  4. 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.

    NOTE

    ChatGPT 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:

  1. You must host this MCP server on a public URL (e.g., via ngrok or a VPS).

  2. 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 tools
homey_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

    A3.6/5.0

    Scored across 19 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      50
      21 npm
      MIT