python-homey

This MCP server provides programmatic access to a HomeyPro integration layer, exposing tools to manage devices, zones, and flows, as well as retrieve system information. It uses FastMCP-compatible tooling to offer paginated lists, search, and action execution (such as triggering flows or controlling devices). The server is designed to be run via uvx (the recommended approach) or directly via the uvx FastMCP runner, and it reads HomeyPro credentials from environment variables. Tools are available to list devices, zones, and flows, fetch detailed device information, manage system configuration, and trigger automations. Users can configure which tools are exposed to clients via environment variables, enabling a lean surface area for clients that only need specific capabilities.

Prerequisites:

• Python 3.8+ and a working Python environment
• uvx (FastMCP virtual environment/runtime)
• Access to a HomeyPro instance with a Personal Access Token

Installation steps:

1. Clone the repository and install dependencies

git clone https://github.com/pigmej/python-homey-mcp.git
cd python-homey-mcp

# Install dependencies (via uvx or your preferred Python environment)
uvx sync

2. Configure environment variables

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

3. Run the server with uvx (recommended)

uvx --from . homey-mcp

4. Optional: run using Makefile targets for development or Docker setup as described in the repository's documentation

make run

Docker usage (optional):

docker pull ghcr.io/pigmej/python-homey-mcp:latest
docker run -e HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS" \
           -e HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN" \
           ghcr.io/pigmej/python-homey-mcp:latest

Tips and common considerations:

• Ensure HOMEY_API_URL is reachable from the host running the MCP server; network restrictions may block access.
• The HOMEY_API_TOKEN should have appropriate permissions for the required operations (read access for listing, write access for control/trigger actions).
• Tools can be selectively enabled/disabled using HOMEY_ENABLED_TOOLS and HOMEY_DISABLED_TOOLS to reduce model confusion in MCP clients.
• When debugging, use the --log-level DEBUG option with uvx to view detailed tool behavior and responses.
• The server supports cursor-based pagination for lists (devices, zones, flows); handle paging in clients to fetch large datasets efficiently.