HomeyPro

You run a Model Context Protocol (MCP) server to interact with your HomeyPro home automation system. It exposes devices, zones, and flows in a practical, paginated API you can drive from MCP clients to list, search, control, and automate your smart home.

How to use

Launch the MCP server using the local runtime, then connect your MCP client to perform common tasks. You will list and search devices, view zones, trigger flows, and inspect system information. Use the provided tools to fetch current device states, apply controls, and execute automations. If HomeyPro is temporarily unavailable, rely on intelligent caching to serve data while gracefully handling errors.

How to install

# Prerequisites
- Python installed on your system (3.x recommended)
- Access to a terminal/command prompt
- Optional: Docker if you prefer containerized execution

# If you want to run locally with the MCP client from this guide
# 1) Clone the project repository (or download the source)
# 2) Install dependencies (via uvx is demonstrated below in the usage section)

Configuration and usage notes

Before you start, set your HomeyPro connection details as environment variables. You provide the API URL and a personal access token to authorize requests.

export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

Runtime start options

The server can be run with MCP client tooling. The following command shows the recommended runtime for development and testing with an MCP client that supports the FastMCP protocol.

uvx fastmcp run main.py --transport stdio

Notes on tooling and environment

Tools and configurations are designed to be enabled or disabled through environment variables at startup. You can tailor which capabilities are exposed by enabling only the tools you need.

Output and status checks

When you run the server, you will get a startup message confirming the connection to HomeyPro. You can verify connectivity and basic health through the system information tool and by checking that flows, devices, and zones respond as expected.

Available tools

list_devices

List all devices with pagination, excluding hidden devices and including online/offline status.

get_device

Retrieve detailed information for a specific device, including capabilities and settings.

get_devices_classes

List all available device classes to understand device types.

get_devices_capabilities

List all possible device capabilities for reference and control options.

search_devices_by_name

Search devices by name with pagination and optional context notes.

search_devices_by_class

Filter devices by class/type with paginated results.

control_device

Set capability values on a device (e.g., on/off, dimming) and return the updated state.

get_device_insights

Fetch historical insights and trends for a device across multiple resolutions.

list_flows

List all flows (normal and advanced) with pagination and complete metadata.

trigger_flow

Trigger a specific flow, with automatic detection of normal vs advanced type.

get_flow_folders

Get the flow folder structure for organization.

get_flows_by_folder

Retrieve flows contained in a specific folder.

get_flows_without_folder

Find flows that are not organized into folders.

list_zones

List all zones with hierarchy and device associations.

get_zone_devices

Get devices within a specific zone, with optional compact mode.

get_zone_temp

Get the average temperature for a zone from zone sensors.

get_system_info

Provide a comprehensive system overview, including counts and health indicators.