Homey Mcp

HomeyPro MCP 服务

一个用于与 HomeyPro 家庭自动化系统交互的 Model Context Protocol（MCP）服务。该服务支持分页访问设备、区域和流程，并提供全面的管理功能。

功能

• 设备管理：列出、搜索和控制设备，支持所有功能
• 区域管理：浏览区域及其关联的设备
• 流程管理：列出并触发自动化流程
• 系统管理：获取和更新系统配置（位置、地址、语言、单位）
• AI 驱动的提示词：针对设备控制、故障排除和自动化提供上下文感知的指导
• 资源缓存：通过智能缓存和过期数据回退机制，高效访问数据
• 分页支持：通过基于游标的分页，高效处理大型数据集
• 实时数据：获取当前设备状态、功能和洞察信息
• 错误处理：提供全面的错误处理和详细的错误消息

安装

本地开发

1. 克隆仓库并进入项目目录：

cd python-homey-mcp

2. 使用 uv 安装依赖：

uv sync

Docker

拉取预构建的 Docker 镜像（支持 AMD64 和 ARM64 架构）：

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

Docker 镜像支持多种架构：

• linux/amd64 - 适用于 Intel/AMD 处理器
• linux/arm64 - 适用于 ARM 处理器（Apple Silicon、Raspberry Pi 等）

Docker 会自动为你的系统拉取正确的架构版本。

构建多架构镜像

要构建自己的多架构 Docker 镜像：

# 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

使用 Docker 时无需执行其他安装步骤。

配置

运行服务前，你需要配置 HomeyPro 连接：

环境变量

设置以下环境变量：

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

可选工具配置

默认情况下，所有单独的工具都已启用。你可以选择性地禁用或启用特定工具，以减少模型混淆：

禁用特定工具

要禁用特定的单独工具，请设置 HOMEY_DISABLED_TOOLS 环境变量：

# 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"

仅启用特定工具

要仅启用特定的单独工具，请设置 HOMEY_ENABLED_TOOLS 环境变量：

# 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"

可用的单独工具：

设备工具：

• list_devices - 分页列出所有设备
• get_device - 获取设备详细信息
• get_devices_classes - 列出可用的设备类别
• get_devices_capabilities - 列出可用的设备功能
• search_devices_by_name - 按名称搜索设备
• search_devices_by_class - 按类别搜索设备
• control_device - 控制设备功能
• get_device_insights - 获取设备洞察信息/分析数据

流程工具：

• list_flows - 列出所有流程（普通和高级）
• trigger_flow - 触发指定流程
• get_flow_folders - 获取流程文件夹结构
• get_flows_by_folder - 获取指定文件夹中的流程
• get_flows_without_folder - 获取未归入任何文件夹的流程

区域工具：

• list_zones - 列出所有区域
• get_zone_devices - 获取指定区域中的设备
• get_zone_temp - 获取区域温度数据

系统工具：

• get_system_info - 获取系统信息和统计数据

**注意：**无论工具配置如何，提示词和资源始终可用。

列出可用工具

要查看当前已启用的工具，可以使用 FastMCP 内置的 list_tools() 方法。已禁用的工具不会显示在此列表中，这是预期行为。

运行 MCP 服务时，客户端只能使用已启用的工具。

实现说明

工具使用标准的 @mcp.tool() 装饰器，并在启动后进行配置：

• 所有工具均通过 @mcp.tool() 正常注册
• 注册后，使用 FastMCP 的 .disable() 方法有选择地禁用工具
• 处理环境变量，以确定要禁用哪些工具
• 被禁用的工具不会出现在 list_tools() 中，也无法调用

这种方式在保持代码简洁的同时，充分利用了 FastMCP 原生的工具管理功能。

获取 HomeyPro 令牌

1. 打开 HomeyPro 网页界面
2. 前往 Settings > General > API
3. 创建新的个人访问令牌
4. 复制令牌并将其设置为 HOMEY_API_TOKEN 环境变量

查找 HomeyPro IP 地址

你可以在以下位置找到 HomeyPro 的 IP 地址：

• HomeyPro 网页界面：Settings > General > Network
• 路由器的管理面板
• HomeyPro 移动应用：More > Settings > General > Network

使用方法

运行服务

使用 uvx（推荐）

运行服务最简单的方法是使用 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

也可以通过 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

本地开发

# 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

开发命令

项目包含一个功能全面的 Makefile，其中提供了实用的开发命令：

# 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

在 MCP 客户端中安装

你可以使用 FastMCP 将此服务直接安装到 MCP 客户端中：

# 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 容器

在 Docker 容器中运行 MCP 服务：

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

也可以使用 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

服务将启动并连接到你的 HomeyPro 实例。你会看到连接确认消息。不过，基本上请以 FastMCP 文档 为准

AI 驱动的提示词

此服务提供上下文感知的提示词，帮助你更高效地与 HomeyPro 系统交互。这些提示词会分析当前系统状态，并提供量身定制的指导。

可用提示词

设备控制助手

提供结构化指导，帮助控制 HomeyPro 系统中的不同类型设备。

• 上下文：当前设备数量、在线／离线状态、可用设备类型
• 指导：照明、温控、安全和娱乐设备的控制模式
• 最佳实践：设备状态检查、能力使用和故障排除技巧

设备故障排除

为常见的 HomeyPro 设备问题提供系统化的诊断指导。

• 系统健康状况：整体设备健康百分比和状态指标
• 分步流程：结构化的故障排除工作流
• 针对设备：针对离线和无响应设备的解决方案
• 高级诊断：网络、性能和系统级故障排除

设备能力探索器

帮助你发现并了解设备能力，同时避免信息过载。

• 能力类别：控制、传感器和状态能力
• 值类型：布尔、数值、字符串和枚举能力格式
• 使用模式：常见能力组合和最佳实践
• 设备类型模式：不同设备类别的能力模式

流程创建助手

为创建 HomeyPro 自动化流程提供结构化指导。

• 流程框架：WHEN（触发条件）、AND（条件）、THEN（操作）结构
• 常见场景：安全、舒适、节能、便利和安全保障自动化
• 系统上下文：可用区域、设备类型和现有流程
• 模板：适用于常见用例的即用型流程模板

流程优化

为提升现有流程的性能和可靠性提供指导。

• 性能分析：流程执行模式和优化机会
• 资源使用情况：设备和系统资源方面的注意事项
• 最佳实践：流程组织、命名和维护策略

流程调试

系统化诊断和修复流程问题的方法。

• 常见问题：流程执行失败、时序问题、设备冲突
• 诊断工具：日志分析、条件测试、操作验证
• 解决策略：逐步调试工作流

系统健康检查

全面分析系统健康状况并提供建议。

• 健康指标：设备连接、流程状态、系统性能
• 状态概览：连接状态、系统配置、资源使用情况
• 建议：维护建议和优化机会

区域组织

关于组织和优化区域结构的指南。

• 区域规划：设备和区域的逻辑分组策略
• 层级管理：父子区域关系
• 设备分配：设备到区域映射的最佳实践

提示词功能

• 上下文感知：所有提示词都会分析当前系统状态
• 实时数据：信息基于当前设备和系统状态
• 优雅降级：即使 HomeyPro 暂时不可用，提示词仍可正常工作
• 错误处理：提供清晰的错误消息和建议操作
• 可操作指导：提供可立即执行的实用步骤

资源缓存

该服务提供智能资源缓存，并在 HomeyPro 暂时不可用时自动回退到过期数据。

可用资源

系统概览（homey://system/overview）

全面的系统概览，包括设备数量、区域数量和健康指标。

• 内容：设备统计、区域摘要、系统健康百分比
• 缓存 TTL：5 分钟
• 适用场景：仪表板显示、系统监控、健康检查

设备注册表（homey://devices/registry）

完整的设备清单，包含当前状态、功能和在线／离线指示。

• 内容：包含功能、状态和元数据的完整设备列表
• 缓存 TTL：30 秒（动态数据）
• 适用场景：设备管理界面、功能发现、状态监控

区域层级（homey://zones/hierarchy）

包含设备关联和父子关系的区域结构。

• 内容：区域树、设备分配、区域类型和统计信息
• 缓存 TTL：5 分钟
• 适用场景：区域管理、设备组织、空间自动化

流程目录（homey://flows/catalog）

包含元数据、状态和执行统计信息的可用流程。

• 内容：包含触发器、条件、操作和执行数据的流程列表
• 缓存 TTL：2 分钟
• 适用场景：流程管理、自动化分析、调试

缓存功能

• 智能 TTL：根据数据波动性采用不同的缓存时长
• 过期数据回退：HomeyPro 无法访问时返回缓存数据
• 错误处理：优雅降级并提供详细的错误信息
• 连接韧性：网络问题期间仍可继续运行
• 性能优化：减少 API 调用并缩短响应时间

缓存行为

1. 新鲜数据：缓存有效且 HomeyPro 可访问时返回当前数据
2. 过期数据：HomeyPro 无法访问时返回缓存数据，并标明数据已过期
3. 错误响应：没有可用的缓存数据时返回结构化错误信息
4. 自动刷新：HomeyPro 恢复可用后，缓存会自动刷新

API 工具

该服务提供全面的 API 工具，可直接与 HomeyPro 交互。所有工具都支持分页和错误处理，并提供详细响应。

设备工具

设备发现与信息

• list_devices：列出所有设备，支持分页

  • 可选紧凑模式，减少数据传输
  • 自动排除隐藏设备
  • 显示每台设备的在线／离线状态

• get_device：获取特定设备的详细信息

  • 完整的设备详情，包括功能和设置
  • 功能值和详细配置
  • 能耗信息和 UI 设置

• get_devices_classes：列出所有可用的设备类别

  • 有助于在搜索前了解设备类型
  • 返回所有受支持的设备类别

• get_devices_capabilities：列出所有可能的设备功能

  • 全面的功能参考
  • 对了解控制选项至关重要

设备搜索与筛选

• search_devices_by_name：按名称搜索设备，支持分页

  • 对设备名称进行模糊匹配
  • 包含备注字段信息，便于了解上下文
  • 支持对大型结果集分页

• search_devices_by_class：按类别／类型搜索设备

  • 按特定类别筛选设备（灯、传感器等）
  • 分页返回结果及元数据

设备控制与监控

• control_device：控制设备功能

  • 设置功能值（开／关、调光、温度等）
  • 解析 JSON 值，失败时进行回退处理
  • 控制后返回设备当前状态

• get_device_insights：获取设备历史数据

  • 支持多种时间分辨率（小时、天、周、月）
  • 支持自定义时间戳范围
  • 提供特定功能的数据分析和趋势

区域工具

区域管理

• list_zones：列出所有区域，支持分页

  • 提供完整的区域层级信息
  • 包含父子关系

• get_zone_devices：获取特定区域内的所有设备

  • 按区域筛选设备
  • 可选紧凑模式以提升性能
  • 显示每台设备的在线／离线状态

区域监控

• get_zone_temp：获取区域的平均温度
  • 自动计算区域内温度传感器的平均值
  • 妥善处理没有温度传感器的区域

工作流工具

统一工作流管理

• list_flows：列出所有工作流（普通和高级），支持分页

  • 自动合并普通和高级工作流
  • 每个工作流都包含 flow_type 字段（"normal" 或 "advanced"）
  • 提供完整的工作流元数据和配置
  • 合并结果后可无缝分页

• trigger_flow：执行任意工作流（自动检测类型）

  • 自动检测工作流是普通还是高级
  • 通过统一接口手动触发工作流
  • 确认执行成功，并提供工作流详情和类型

• get_flow_folders：获取所有工作流组织文件夹

  • 工作流组织结构
  • 文件夹层级便于管理

• get_flows_by_folder：获取特定文件夹中的工作流

  • 按文件夹筛选工作流
  • 工作流组织管理

• get_flows_without_folder：获取未整理的工作流

  • 查找需要整理的工作流
  • 协助清理和维护

工作流整理

• get_flow_folders：获取所有工作流组织文件夹

  • 工作流组织结构
  • 文件夹层级便于管理

• get_flows_by_folder：获取特定文件夹中的工作流

  • 按文件夹筛选工作流
  • 工作流组织管理
  • 注意：仅返回文件夹中的普通工作流

• get_flows_without_folder：获取未整理的工作流

  • 查找需要整理的工作流
  • 协助清理和维护
  • 注意：仅返回未归入文件夹的普通工作流

系统工具

系统信息

• get_system_info：获取全面的系统概览
  • 连接状态和系统健康状况
  • 设备、区域和工作流数量
  • 在线／离线设备统计
  • 工作流状态（已启用／已禁用／故障）
  • 系统配置（地址、语言、单位）
  • 位置坐标和区域设置
  • 建议在执行其他操作前首先调用

工具特性

分页支持

• 基于游标的分页：高效处理大型数据集
• 可配置的页面大小：根据使用场景进行优化
• 总数跟踪：了解完整数据集的大小
• 下一页指示器：轻松浏览结果

数据格式

• 紧凑模式：减少数据传输，提升性能
• 完整详细模式：按需获取完整信息
• JSON 值处理：自动解析并提供回退机制
• 错误响应：提供包含详细信息的结构化错误信息

性能优化

• 隐藏设备过滤：自动排除系统设备
• 高效查询：优化对 HomeyPro 的 API 调用
• 连接复用：保持连接以提升性能
• 平稳降级：部分故障期间仍可继续运行

错误处理

• 详细错误消息：清晰描述问题
• 连接状态：网络和 API 健康状况指示器
• 回退响应：妥善处理 API 故障
• 日志集成：全面跟踪错误

贡献

1. 复刻此代码仓库
2. 创建功能分支
3. 进行更改
4. 在适用时添加测试
5. 提交拉取请求

许可证

本项目采用 MIT License。