pigmej/python-homey-mcp

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:

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

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"

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

Local Development

uv run fastmcp run -t http --host 0.0.0.0 -p 4445 -l DEBUG main.py

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

Basic Flow Management

• list_flows: List all standard flows with pagination

  • Complete flow metadata and configuration
  • Trigger, condition, and action information

• trigger_flow: Execute a specific flow

  • Manual flow triggering
  • Success confirmation with flow details

• 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

Advanced Flow Management

• list_advanced_flows: List all advanced flows

  • Complex automation flows with scripting
  • Complete flow structure and metadata

• get_advanced_flow: Get detailed advanced flow information

  • Full flow configuration and logic
  • Script content and execution details

• trigger_advanced_flow: Execute advanced flows

  • Manual triggering of complex automations
  • Execution confirmation and status

Advanced Flow Search and Filtering

• search_advanced_flows: Search advanced flows by name/description

  • Text-based flow discovery
  • Paginated search results

• get_enabled_advanced_flows: Get only enabled advanced flows

  • Active automation discovery
  • Performance and maintenance insights

• get_disabled_advanced_flows: Get disabled advanced flows

  • Inactive flow identification
  • Maintenance and cleanup assistance

• get_broken_advanced_flows: Get flows with errors

  • Error detection and troubleshooting
  • System health monitoring

• get_advanced_flows_by_folder: Get advanced flows in folders

  • Organized advanced flow management
  • Folder-based filtering

• get_advanced_flows_without_folder: Get unorganized advanced flows

  • Organization and cleanup assistance
  • Flow management optimization

• get_advanced_flows_with_inline_scripts: Get flows containing scripts

  • Script-based automation identification
  • Advanced functionality discovery

Flow State Management

• enable_advanced_flow: Enable a disabled advanced flow

  • Flow activation with confirmation
  • State management and control

• disable_advanced_flow: Disable an active advanced flow

  • Flow deactivation for maintenance
  • Temporary automation suspension

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.