# 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:
```bash
cd python-homey-mcp
```
2. Install dependencies using uv:
```bash
uv sync
```
### Docker
Pull the pre-built Docker image:
```bash
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:
```bash
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
```bash
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:
```bash
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:
```yaml
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](https://gofastmcp.com/patterns/cli)
## 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.