星战科技xingzhan.cloud
返回市场
python家居-mcp

python家居-mcp

作者：pigmej6 星标更新：2025-09-09
安装使用来源：spider==github.com

项目介绍

HomeyPro MCP 服务器

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

功能

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

安装

本地开发

  1. 克隆仓库并导航到项目目录：
cd python-homey-mcp
  1. 使用 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 镜像：

# 设置 Docker Buildx（一次性设置）
./setup-buildx.sh

# 仅构建当前平台
make docker-build

# 构建 AMD64 和 ARM64
make docker-build-multi

# 构建并推送到注册表
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 环境变量：

# 禁用设备控制和洞察工具（保留设备列表和搜索）
export HOMEY_DISABLED_TOOLS="control_device,get_device_insights"

# 禁用所有设备管理工具
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 环境变量：

# 仅启用系统信息和区域列表（最小配置）
export HOMEY_ENABLED_TOOLS="get_system_info,list_zones"

# 启用基本的设备和区域管理而不具备控制功能
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：

# 设置您的环境变量
export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

# 使用 uvx 运行
uvx --from . homey-mcp

或者直接使用 FastMCP CLI 运行：

# HTTP 传输（推荐用于测试）
uvx fastmcp run main.py --transport http --host 0.0.0.0 --port 4445

# STDIO 传输（用于 MCP 客户端）
uvx fastmcp run main.py --transport stdio

本地开发

# 使用 uv run
uv run fastmcp run main.py --transport http --host 0.0.0.0 --port 4445 --log-level DEBUG

# 或者旧的方式
uv run fastmcp run -t http --host 0.0.0.0 -p 4445 -l DEBUG main.py

# 或者使用 Makefile
make run

开发命令

该项目包含一个综合的 Makefile，其中包含有用的开发命令：

# 设置和安装
make setup              # 初始设置（安装 + 检查环境）
make install            # 安装依赖项
make check-env          # 验证环境配置

# 开发工作流
make test               # 运行测试套件
make lint               # 运行代码检查
make format             # 格式化代码
make clean              # 清理生成的文件

# Docker 操作
make docker-build       # 为当前平台构建 Docker 镜像
make docker-build-multi # 构建多架构镜像（AMD64 + ARM64）
make docker-push        # 构建并推送多架构镜像
make docker-test        # 测试 Docker 镜像

# 工具
make info               # 显示项目信息
make check-connection   # 测试 HomeyPro 连接

在 MCP 客户端中安装

您可以直接在 MCP 客户端中安装此服务器，使用 FastMCP：

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

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

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

# 生成 MCP JSON 配置
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：列出所有流程（普通和高级），支持分页
    • 自动合并普通