HomeyPro MCP Server

A Model Context Protocol (MCP) server for interacting with HomeyPro home automation systems. This server provides paginated access to devices, zones, and flows with comprehensive management capabilities.

Features

• Device Management: List, search, and control devices with full capability support
• Zone Management: Browse zones and their associated devices
• Flow Management: List and trigger automation flows
• System Management: Get and update system configuration (location, address, language, units)
• AI-Powered Prompts: Context-aware guidance for device control, troubleshooting, and automation
• Resource Caching: Efficient data access with intelligent caching and stale data fallback
• Pagination Support: Efficient handling of large datasets with cursor-based pagination
• Real-time Data: Get current device states, capabilities, and insights
• Error Handling: Comprehensive error handling with detailed error messages

Installation

Local Development

1. Clone the repository and navigate to the project directory:

cd python-homey-mcp

2. Install dependencies using uv:

uv sync

Docker

Pull the pre-built Docker image (supports both AMD64 and ARM64 architectures):

docker pull ghcr.io/pigmej/python-homey-mcp:latest

The Docker image is built for multiple architectures:

• linux/amd64 - For Intel/AMD processors
• linux/arm64 - For ARM processors (Apple Silicon, Raspberry Pi, etc.)

Docker will automatically pull the correct architecture for your system.

Building Multi-Architecture Images

To build your own multi-architecture Docker images:

# Setup Docker Buildx (one-time setup)
./setup-buildx.sh

# Build for current platform only
make docker-build

# Build for both AMD64 and ARM64
make docker-build-multi

# Build and push to registry
make docker-push

No additional installation steps are required when using Docker.

Configuration

Before running the server, you need to configure your HomeyPro connection:

Environment Variables

Set the following environment variables:

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

Optional Tools Configuration

By default, all individual tools are enabled. You can selectively disable or enable specific tools to reduce model confusion:

Disable Specific Tools

To disable specific individual tools, set the HOMEY_DISABLED_TOOLS environment variable:

# Disable device control and insights tools (keep device listing and search)
export HOMEY_DISABLED_TOOLS="control_device,get_device_insights"

# Disable all device management tools
export HOMEY_DISABLED_TOOLS="list_devices,get_device,get_devices_classes,get_devices_capabilities,search_devices_by_name,search_devices_by_class,control_device,get_device_insights"

Enable Only Specific Tools

To enable only specific individual tools, set the HOMEY_ENABLED_TOOLS environment variable:

# Enable only system info and zone listing (minimal configuration)
export HOMEY_ENABLED_TOOLS="get_system_info,list_zones"

# Enable basic device and zone management without control capabilities
export HOMEY_ENABLED_TOOLS="get_system_info,list_devices,get_device,list_zones,get_zone_devices"

Available individual tools:

Device Tools:

• list_devices - List all devices with pagination
• get_device - Get detailed device information
• get_devices_classes - List available device classes
• get_devices_capabilities - List available device capabilities
• search_devices_by_name - Search devices by name
• search_devices_by_class - Search devices by class
• control_device - Control device capabilities
• get_device_insights - Get device insights/analytics

Flow Tools:

• list_flows - List all flows (normal and advanced)
• trigger_flow - Trigger a specific flow
• get_flow_folders - Get flow folder structure
• get_flows_by_folder - Get flows in a specific folder
• get_flows_without_folder - Get flows not in any folder

Zone Tools:

• list_zones - List all zones
• get_zone_devices - Get devices in a specific zone
• get_zone_temp - Get temperature data for a zone

System Tools:

• get_system_info - Get system information and statistics

Note: Prompts and resources are always available regardless of tool configuration.

List Available Tools

To see which tools are currently enabled, you can use FastMCP's built-in list_tools() method. Disabled tools will not appear in this list, which is the intended behavior.

When running the MCP server, only enabled tools will be available to clients.

Implementation Notes

Tools use standard @mcp.tool() decorators and are configured post-startup:

• All tools are registered normally with @mcp.tool()
• After registration, tools are selectively disabled using FastMCP's .disable() method
• Environment variables are processed to determine which tools to disable
• Disabled tools won't appear in list_tools() and can't be called

This approach keeps the code simple while leveraging FastMCP's native tool management.

Getting Your HomeyPro Token

1. Open the HomeyPro web interface
2. Go to Settings > General > API
3. Create a new Personal Access Token
4. Copy the token and set it as the HOMEY_API_TOKEN environment variable

Finding Your HomeyPro IP Address

You can find your HomeyPro's IP address in:

• HomeyPro web interface: Settings > General > Network
• Your router's admin panel
• HomeyPro mobile app: More > Settings > General > Network

Usage

Running the Server

Using uvx (Recommended)

The easiest way to run the server is using uvx:

# Set your environment variables
export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

# Run with uvx
uvx --from . homey-mcp

Or run directly with FastMCP CLI:

# HTTP transport (recommended for testing)
uvx fastmcp run main.py --transport http --host 0.0.0.0 --port 4445

# STDIO transport (for MCP clients)
uvx fastmcp run main.py --transport stdio

Local Development

# Using uv run
uv run fastmcp run main.py --transport http --host 0.0.0.0 --port 4445 --log-level DEBUG

# Or the old way
uv run fastmcp run -t http --host 0.0.0.0 -p 4445 -l DEBUG main.py

# Or using Makefile
make run

Development Commands

The project includes a comprehensive Makefile with useful development commands:

# Setup and installation
make setup              # Initial setup (install + check environment)
make install            # Install dependencies
make check-env          # Verify environment configuration

# Development workflow
make test               # Run test suite
make lint               # Run linting checks
make format             # Format code
make clean              # Clean up generated files

# Docker operations
make docker-build       # Build Docker image for current platform
make docker-build-multi # Build multi-architecture image (AMD64 + ARM64)
make docker-push        # Build and push multi-architecture image
make docker-test        # Test Docker image

# Utilities
make info               # Show project information
make check-connection   # Test HomeyPro connection

Installing in MCP Clients

You can install this server directly in MCP clients using FastMCP:

# Install in Claude Desktop
uvx fastmcp install claude-desktop main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

# Install in Claude Code
uvx fastmcp install claude-code main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

# Install in Cursor
uvx fastmcp install cursor main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

# Generate MCP JSON config
uvx fastmcp install mcp-json main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

Docker Container

Run the MCP server in a Docker container:

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

Or using docker-compose:

version: '3.8'
services:
  python-homey-mcp:
    image: ghcr.io/pigmej/python-homey-mcp:latest
    ports:
      - "4445:4445"
    environment:
      - HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS
      - HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

The server will start and connect to your HomeyPro instance. You'll see a connection confirmation message. But basically please yield to FastMCP docs

AI-Powered Prompts

The server provides context-aware prompts that help you interact with your HomeyPro system more effectively. These prompts analyze your current system state and provide tailored guidance.

Available Prompts

Device Control Assistant

Provides structured guidance for controlling different types of devices in your HomeyPro system.

• Context: Current device counts, online/offline status, available device types
• Guidance: Control patterns for lighting, climate, security, and entertainment devices
• Best Practices: Device status checking, capability usage, troubleshooting tips

Device Troubleshooting

Systematic diagnostic guidance for common HomeyPro device issues.

• System Health: Overall device health percentage and status indicators
• Step-by-Step Process: Structured troubleshooting workflow
• Device-Specific: Targeted solutions for offline and unresponsive devices
• Advanced Diagnostics: Network, performance, and system-level troubleshooting

Device Capability Explorer

Helps you discover and understand device capabilities without overwhelming detail.

• Capability Categories: Control, sensor, and status capabilities
• Value Types: Boolean, numeric, string, and enum capability formats
• Usage Patterns: Common capability combinations and best practices
• Device Type Patterns: Capability patterns for different device categories

Flow Creation Assistant

Structured guidance for creating HomeyPro automation flows.

• Flow Framework: WHEN (trigger), AND (conditions), THEN (actions) structure
• Common Scenarios: Security, comfort, energy, convenience, and safety automations
• System Context: Available zones, device types, and existing flows
• Templates: Ready-to-use flow templates for common use cases

Flow Optimization

Guidance for improving existing flow performance and reliability.

• Performance Analysis: Flow execution patterns and optimization opportunities
• Resource Usage: Device and system resource considerations
• Best Practices: Flow organization, naming, and maintenance strategies

Flow Debugging

Systematic approach to diagnosing and fixing flow issues.

• Common Problems: Flow execution failures, timing issues, device conflicts
• Diagnostic Tools: Log analysis, condition testing, action verification
• Resolution Strategies: Step-by-step debugging workflow

System Health Check

Comprehensive system health analysis and recommendations.

• Health Indicators: Device connectivity, flow status, system performance
• Status Overview: Connection status, system configuration, resource usage
• Recommendations: Maintenance suggestions and optimization opportunities

Zone Organization

Guidance for organizing and optimizing zone structure.

• Zone Planning: Logical grouping strategies for devices and areas
• Hierarchy Management: Parent-child zone relationships
• Device Assignment: Best practices for device-to-zone mapping

Prompt Features

• Context-Aware: All prompts analyze your current system state
• Real-Time Data: Information is based on current device and system status
• Graceful Degradation: Prompts work even when HomeyPro is temporarily unavailable
• Error Handling: Clear error messages with suggested actions
• Actionable Guidance: Practical steps you can take immediately

Resource Caching

The server provides intelligent resource caching with automatic fallback to stale data when HomeyPro is temporarily unavailable.

Available Resources

System Overview (homey://system/overview)

Comprehensive system overview including device counts, zone counts, and health indicators.

• Content: Device statistics, zone summary, system health percentage
• Cache TTL: 5 minutes
• Use Case: Dashboard displays, system monitoring, health checks

Device Registry (homey://devices/registry)

Complete device inventory with current states, capabilities, and online/offline indicators.

• Content: Full device list with capabilities, states, and metadata
• Cache TTL: 30 seconds (dynamic data)
• Use Case: Device management interfaces, capability discovery, status monitoring

Zone Hierarchy (homey://zones/hierarchy)

Zone structure with device associations and parent-child relationships.

• Content: Zone tree, device assignments, zone types and statistics
• Cache TTL: 5 minutes
• Use Case: Zone management, device organization, spatial automation

Flow Catalog (homey://flows/catalog)

Available flows with metadata, status, and execution statistics.

• Content: Flow list with triggers, conditions, actions, and execution data
• Cache TTL: 2 minutes
• Use Case: Flow management, automation analysis, debugging

Caching Features

• Intelligent TTL: Different cache durations based on data volatility
• Stale Data Fallback: Returns cached data when HomeyPro is unreachable
• Error Handling: Graceful degradation with detailed error information
• Connection Resilience: Continues operation during network issues
• Performance Optimization: Reduces API calls and improves response times

Cache Behavior

1. Fresh Data: Returns current data when cache is valid and HomeyPro is accessible
2. Stale Data: Returns cached data with staleness indicators when HomeyPro is unreachable
3. Error Response: Returns structured error information when no cached data is available
4. Automatic Refresh: Cache automatically refreshes when HomeyPro becomes available again

API Tools

The server provides comprehensive API tools for direct HomeyPro interaction. All tools support pagination and error handling with detailed responses.

Device Tools

Device Discovery and Information

• list_devices: List all devices with pagination support

  • Optional compact mode for reduced data transfer
  • Excludes hidden devices automatically
  • Includes online/offline status for each device

• get_device: Get detailed information about a specific device

  • Complete device details including capabilities and settings
  • Capability values and detailed configuration
  • Energy information and UI settings

• get_devices_classes: List all available device classes

  • Useful for understanding device types before searching
  • Returns complete list of supported device categories

• get_devices_capabilities: List all possible device capabilities

  • Comprehensive capability reference
  • Essential for understanding control options

Device Search and Filtering

• search_devices_by_name: Search devices by name with pagination

  • Fuzzy matching against device names
  • Includes note field information for context
  • Supports pagination for large result sets

• search_devices_by_class: Search devices by class/type

  • Filter devices by specific categories (lights, sensors, etc.)
  • Paginated results with metadata

Device Control and Monitoring

• control_device: Control device capabilities

  • Set capability values (on/off, dimming, temperature, etc.)
  • JSON value parsing with fallback handling
  • Returns current device state after control

• get_device_insights: Get historical device data

  • Multiple time resolutions (hour, day, week, month)
  • Custom timestamp ranges supported
  • Capability-specific insights and trends

Zone Tools

Zone Management

• list_zones: List all zones with pagination

  • Complete zone hierarchy information
  • Parent-child relationships included

• get_zone_devices: Get all devices in a specific zone

  • Zone-based device filtering
  • Compact mode option for performance
  • Online/offline status per device

Zone Monitoring

• get_zone_temp: Get average temperature for a zone
  • Automatically averages temperature sensors in the zone
  • Handles zones without temperature sensors gracefully

Flow Tools

Unified Flow Management

• list_flows: List all flows (both normal and advanced) with pagination

  • Automatically combines normal and advanced flows
  • Each flow includes a flow_type field ("normal" or "advanced")
  • Complete flow metadata and configuration
  • Seamless pagination across combined results

• trigger_flow: Execute any flow (automatically detects type)

  • Automatically detects whether flow is normal or advanced
  • Manual flow triggering with unified interface
  • Success confirmation with flow details and type

• get_flow_folders: Get all flow organization folders

  • Flow organization structure
  • Folder hierarchy for better management

• get_flows_by_folder: Get flows in a specific folder

  • Folder-based flow filtering
  • Organizational flow management

• get_flows_without_folder: Get unorganized flows

  • Find flows that need organization
  • Cleanup and maintenance assistance

Flow Organization

• get_flow_folders: Get all flow organization folders

  • Flow organization structure
  • Folder hierarchy for better management

• get_flows_by_folder: Get flows in a specific folder

  • Folder-based flow filtering
  • Organizational flow management
  • Note: Only returns normal flows in folder

• get_flows_without_folder: Get unorganized flows

  • Find flows that need organization
  • Cleanup and maintenance assistance
  • Note: Only returns normal flows without folder

System Tools

System Information

• get_system_info: Get comprehensive system overview
  • Connection status and system health
  • Device, zone, and flow counts
  • Online/offline device statistics
  • Flow status (enabled/disabled/broken)
  • System configuration (address, language, units)
  • Location coordinates and regional settings
  • Recommended as first call before other operations

Tool Features

Pagination Support

• Cursor-based pagination: Efficient handling of large datasets
• Configurable page sizes: Optimize for your use case
• Total count tracking: Know the full dataset size
• Next page indicators: Easy navigation through results

Data Formats

• Compact mode: Reduced data transfer for performance
• Full detail mode: Complete information when needed
• JSON value handling: Automatic parsing with fallbacks
• Error responses: Structured error information with details

Performance Optimization

• Hidden device filtering: Automatic exclusion of system devices
• Efficient queries: Optimized API calls to HomeyPro
• Connection reuse: Persistent connections for better performance
• Graceful degradation: Continues operation during partial failures

Error Handling

• Detailed error messages: Clear problem descriptions
• Connection status: Network and API health indicators
• Fallback responses: Graceful handling of API failures
• Logging integration: Comprehensive error tracking

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License.