Homey Mcp

Name: Homey Mcp
Author: pigmej

@pigmej

Repository

About Homey Mcp

# HomeyPro MCP Server

#homeypro #home-automation #mcp-server

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "python-homey-mcp": {
      "command": "uv",
      "args": [
        "sync"
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Homey Mcp?

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

How to use Homey Mcp?

Configure the HOMEY_API_URL and HOMEY_API_TOKEN environment variables, then run the server using uvx, Docker, or install it directly into MCP clients (Claude Desktop, Claude Code, Cursor) via FastMCP CLI.

Key features of Homey Mcp

Device management with full capability support
Zone browsing and management
Flow listing and triggering
System configuration management
AI-powered context-aware prompts for guidance
Intelligent resource caching with stale data fallback
Pagination support for large datasets
Comprehensive error handling with detailed messages

Use cases of Homey Mcp

Control and monitor HomeyPro devices via AI assistants
Create, debug, and optimize automation flows
Organize and browse zones and device hierarchies
Perform system health checks and diagnostics
Discover device capabilities and control patterns

FAQ from Homey Mcp

What environment variables are required?

HOMEY_API_URL (the IP address of your HomeyPro) and HOMEY_API_TOKEN (a personal access token from HomeyPro settings).

How do I obtain a HomeyPro API token?

Go to the HomeyPro web interface, navigate to Settings > General > API, and create a new Personal Access Token.

What transport protocols does the server support?

HTTP transport (recommended for testing) and STDIO transport (for MCP clients).

Can I run the server in Docker?

Yes, a pre-built Docker image is available at ghcr.io/pigmej/python-homey-mcp:latest. Run it with the required environment variables.

What data is cached and for how long?

System overview (5 min TTL), device registry (30 sec), zone hierarchy (5 min), and flow catalog (2 min). When HomeyPro is unreachable, stale cached data is returned with staleness indicators.