HomeyPro MCP Server

HomeyPro MCP服务器

用于与HomeyPro家庭自动化系统交互的模型上下文协议（MCP）服务器。此服务器提供对设备、区域和流的分页访问，并具有全面的管理功能。

特性

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

安装

地方发展

1. 克隆存储库并导航到项目目录：

cd python-homey-mcp

1. 使用uv安装依赖项：

uv sync

码头工人

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

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

Docker镜像是为多种架构构建的：

• linux/amd64 -适用于Intel/AMD处理器
• linux/arm64 -适用于ARM处理器（苹果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. 前往“设置”>“常规”>“API”
3. 创建新的个人访问令牌
4. 复制令牌并将其设置为 HOMEY_API_TOKEN 环境变量

查找您的HomeyPro IP地址

您可以在以下网址找到HomeyPro的IP地址：

• HomeyPro网络界面：设置>常规>网络
• 路由器的管理面板
• HomeyPro移动应用程序：更多>设置>常规>网络

用法

运行服务器

使用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文档

人工智能提示

服务器提供上下文感知提示，帮助您更有效地与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 字段（“正常”或“高级”） - 完整的流元数据和配置 - 跨组合结果进行无缝分页

• 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许可证获得许可。