Homey-Wan-Kenobi MCP

Name: Homey-Wan-Kenobi MCP
Author: Ringosystems

本地服务

github.com其他117 周前更新

代码仓库访问官网

关于 Homey-Wan-Kenobi MCP

Homey-Wan-Kenobi MCP 是面向 Homey Pro 的自托管 MCP 服务，可通过自然语言管理智能家居设备和自动化。它提供设备、能源、流程及 Z-Wave/Zigbee 网络诊断能力，并支持 stdio 与 streamable-HTTP。

主要功能

01控制和管理设备与区域
02创建、编辑和运行流程
03查看能源报告与历史传感器数据
04诊断 Z-Wave 和 Zigbee 网络
05检查备份、内存和存储状态

适用场景

01通过自然语言控制 Homey Pro 设备
02从头创建或调整 Homey 自动化流程
03调查能源使用和传感器历史变化
04排查无线网状网络及设备连接问题

MCP 相关

该服务将 Homey Pro 的设备、流程、能源和诊断操作作为工具及提示词提供给 MCP 客户端。支持 stdio 和 streamable-HTTP 传输，可自行托管。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ringosystems-homey-wan-kenobi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HOMEY_ADDRESS",
        "-e",
        "HOMEY_TOKEN",
        "docker.io/ringosystems/homey-wan-kenobi:2.2.0"
      ],
      "env": {
        "HOMEY_ADDRESS": "<HOMEY_ADDRESS>",
        "HOMEY_TOKEN": "<HOMEY_TOKEN>"
      }
    }
  }
}

启动命令docker run -i --rm -e HOMEY_ADDRESS -e HOMEY_TOKEN docker.io/ringosystems/homey-wan-kenobi:2.2.0

需要配置的环境变量

HOMEY_ADDRESSBase URL of your Homey Pro local API, e.g. http://192.168.1.10

HOMEY_TOKEN密钥Homey local API key (my.homey.app > Settings > API keys)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocidocker.io/ringosystems/homey-wan-kenobi:2.2.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Homey-Wan-Kenobi MCP

用于通过 Model Context Protocol 控制 Homey Pro 智能家居系统的 MCP 服务。

这个名字致敬 Obi-Wan Kenobi，他是你家中以自然语言进行控制的唯一希望。

提供 60 个工具和 3 个知识提示词，用于设备控制、流程编写、自动化、监控、故障排查、网络诊断和自托管部署。

为什么选择 Homey-Wan-Kenobi

Athom 提供官方的 Homey MCP Server：一种由云端代理的远程连接器，你可以将其添加到付费 Claude 或 ChatGPT 计划中，并使用 Homey 账号登录。它支持设备状态和控制、重命名及移动设备、创建、更新和启动 Flows 与 Advanced Flows，以及设置 Moods。

这个服务有两点不同。它是可自托管的，因此你可以通过 stdio 或 streamable-HTTP 自行运行，无需第三方代理，也不要求付费 AI 计划。此外，它还为高级用户提供了更深入的运维能力，这些能力不属于官方服务所描述的功能。

下表反映了截至 2026 年 6 月 Athom 公开描述的功能。Athom 未发布正式的工具列表，因此右侧列出的功能差异是根据其文档推断得出的，并非 Athom 明确说明。

功能	官方 Homey MCP（`mcp.athom.com`）	Homey-Wan-Kenobi
托管方式	云端代理的远程连接器	自托管，支持 stdio 或 HTTP，无需代理
访问方式	付费 Claude/ChatGPT 连接器计划	支持任何 MCP 客户端，无需订阅计划
设备、区域、控制、重命名、移动	支持	支持
Flow 和 Advanced Flow 编写	支持	支持
Moods	支持	支持
Flow 卡片架构发现（从头构建流程）	未说明	支持
能源：实时功率和日／周／月／年报告	未说明	支持
Insights：传感器和电表历史数据	未说明	支持
Z-Wave 和 Zigbee 网状网络诊断及修复建议	未说明	支持
应用记忆和使用情况分析（可移除项）	未说明	支持
基础设施运维：备份、重启、更新、内存、存储	未说明	支持
原始 Homey Web API 透传	未说明	支持
列入公开 MCP Registry	否	是

实际能力深度

官方服务未涵盖的网络诊断。 diagnose_zwave_network 和 diagnose_zigbee_network 会读取控制器运行状况，根据每个节点的最近活动时间评估其状态（考虑电池供电设备的休眠情况），对传输失败进行分组，将其与不可用设备关联，并按严重程度排序返回修复建议。get_zwave_log 可查看原始网络日志。
能源与 Insights 分析。 按区域和设备查看实时功率、日／周／月／年能源报告，以及带时间戳的历史传感器和电表数据，帮助模型回答“现在什么设备在耗电？”或“本周卧室温度的变化趋势如何？”等问题。
应用内存与使用情况分析。 analyze_app_usage 会交叉比对每个应用的 RAM 占用、设备数量和流程引用，标记可安全移除的候选应用并估算可节省的资源。此工具只读且仅提供建议。
从头构建自动化。 流程卡发现引擎（list_flow_cards、get_flow_card）会返回每张卡的完整参数架构；完整的标准流程和 Advanced Flow CRUD（包括删除）支持 AI 按 UUID 创建和拆除整个卡片图。
通过一个接口执行基础设施操作。 备份、重启、更新检查、内存和存储用量、驱动、LED 环、会话和位置信息。
面向未来的备用通道。 homey_api_call 可直接访问任意 Homey Web API 端点，因此无需等待工具更新即可使用新的固件功能。

该服务运行在经过加固的非 root node:22-alpine 镜像中，每次构建和发布都必须通过 Trivy 扫描，并发布到 Docker Hub、GHCR 和公共 MCP Registry。完整列表请参阅下方的工具参考。

适合选择官方服务的情况

此服务优先支持本地使用且可自托管，这是它的优势，也意味着一定的取舍。在以下情况下，官方 Homey MCP 是更简单的选择：

无需设置，由服务托管。 添加一个 URL 并使用 Homey 账号登录即可。无需运行、公开或维护容器，并且提供一键式 ChatGPT 应用。
安全地从任何位置远程访问。 Athom 通过其云端中转连接，因此即使不在家，也无需向局域网公开任何内容即可使用。此服务的 HTTP 模式面向可信的本地网络；如需远程使用，请自行配置 VPN 或经过身份验证的反向代理。
支持所有 Homey 型号。 官方端点可连接 Homey Cloud、Pro、Pro mini 和 Self-Hosted Server，包括没有本地 API 的纯云端配置。此服务面向可通过本地 API 或 Athom 令牌访问的 Homey，因此最适合 Homey Pro。
一手支持。 此服务由 Athom 维护，与固件同步更新，并经过官方测试，可与 Claude 和 ChatGPT 应用配合使用。此项目独立维护，尽力提供支持。

两者相辅相成。许多人使用官方连接器进行快速远程控制，并使用此服务执行深入的本地诊断、能源分析和基础设施操作。Athom 未公布正式的工具列表，因此官方服务也可能包含上文未提及的功能。

快速开始

git clone https://github.com/Ringosystems/Homey-Wan-Kenobi-MCP.git
cd Homey-Wan-Kenobi-MCP
npm install
npm run build

使用 Homey 进行身份验证：

npx homey login
npx homey select

将其添加到 MCP 客户端配置中（Kiro、Claude Desktop、Cline 等）：

{
  "mcpServers": {
    "homey": {
      "command": "node",
      "args": ["/path/to/Homey-Wan-Kenobi-MCP/dist/index.js"]
    }
  }
}

身份验证

此服务支持两种身份验证方式：

Homey CLI（推荐）：运行 npx homey login 和 npx homey select。服务会自动从 ~/.athom-cli/settings.json 读取已保存的 OAuth 令牌。

本地 API 密钥：在 my.homey.app 创建。设置环境变量：

export HOMEY_ADDRESS=http://192.168.1.x
export HOMEY_TOKEN=your-api-key

在容器中运行可自托管服务时，推荐使用本地 API 密钥方式，因为它不依赖挂载的 CLI 设置文件。

自托管（Docker / HTTP）

此镜像发布于 ringosystems/homey-wan-kenobi（镜像同步至 ghcr.io/ringosystems/homey-wan-kenobi），该服务已在 MCP Registry 中登记，名称为 io.github.Ringosystems/homey-wan-kenobi-mcp。它基于 node:22-alpine 构建，以非 root 用户身份运行，且不包含预置密钥。审计详情请参阅 SECURITY.md。

默认使用 stdio 传输方式，因此 MCP 客户端可以直接启动它；设置 MCP_TRANSPORT=streamable-http 后，它会通过 supergateway 在 /mcp 提供长连接的 streamable-HTTP 服务，并在 /healthz 提供健康检查。

最快方式：一条命令（预构建镜像）

无需克隆或构建。拉取两个镜像并启动：

curl -fsSLO https://raw.githubusercontent.com/Ringosystems/Homey-Wan-Kenobi-MCP/main/docker-compose.deploy.yml
printf 'HOMEY_ADDRESS=http://192.168.1.x\nHOMEY_TOKEN=your-local-api-key\n' > .env
docker compose -f docker-compose.deploy.yml up -d

随后可通过 http://<host>:8000/mcp 访问服务（健康检查地址为 /healthz）。在 Unraid 上，请改为通过 URL 添加模板：依次选择 Docker、Add Container，然后将 https://raw.githubusercontent.com/Ringosystems/Homey-Wan-Kenobi-MCP/main/deploy/unraid/homey-wan-kenobi.xml 粘贴到 Template 字段。该镜像支持多种架构，可在 x86 和 ARM（Apple Silicon、Raspberry Pi）主机上运行。

/mcp 端点没有内置身份验证。请仅在可信的局域网中使用，或置于可提供 TLS 和身份验证的反向代理之后。

作为 MCP 客户端运行（stdio）

docker run -i --rm \
  -e HOMEY_ADDRESS=http://192.168.1.x \
  -e HOMEY_TOKEN=your-local-api-key \
  ringosystems/homey-wan-kenobi:latest

作为 HTTP 服务运行

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e HOMEY_ADDRESS=http://192.168.1.x \
  -e HOMEY_TOKEN=your-local-api-key \
  --restart unless-stopped \
  ringosystems/homey-wan-kenobi:latest

Docker Compose

在 docker-compose.yml 同级目录下创建 .env 文件，并在其中提供 Homey 凭据：

cat > .env <<'EOF'
HOMEY_ADDRESS=http://192.168.1.x
HOMEY_TOKEN=your-local-api-key
EOF

# Pull the published image, or add --build to build locally instead
docker compose up -d

提供的 docker-compose.yml 引用了已发布的镜像（并将 build: . 作为本地构建的备用方案），同时对容器进行了加固（只读根文件系统、移除 Linux 功能、启用 no-new-privileges，并设置内存和 PID 限制）：

services:
  homey-wan-kenobi:
    image: ringosystems/homey-wan-kenobi:latest
    build: .
    container_name: homey-wan-kenobi
    ports:
      - "8000:8000"
    environment:
      MCP_TRANSPORT: streamable-http
      HOMEY_ADDRESS: "${HOMEY_ADDRESS:-http://192.168.1.x}"
      HOMEY_TOKEN: "${HOMEY_TOKEN:-}"
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    mem_limit: 256m
    pids_limit: 128
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:8000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

本地构建

docker build -t ringosystems/homey-wan-kenobi .
docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e HOMEY_ADDRESS=http://192.168.1.x \
  -e HOMEY_TOKEN=your-local-api-key \
  --restart unless-stopped \
  ringosystems/homey-wan-kenobi

连接客户端

将 MCP 客户端指向 streamable-HTTP 端点：

{
  "mcpServers": {
    "homey": {
      "type": "streamable-http",
      "url": "http://your-host:8000/mcp"
    }
  }
}

使用 curl http://your-host:8000/healthz 检查健康状态。

工具

设备

工具	说明
`list_devices`	列出设备及其实时功能值，可按区域或类别筛选
`get_device`	按 ID 获取设备的完整详情及所有功能值
`search_devices`	按名称、类别或功能搜索设备
`set_device_capability`	控制设备（onoff、dim、target_temperature、volume_set 等）

设备和区域管理

工具	说明
`rename_device`	重命名设备
`move_device_to_zone`	将设备移至其他区域（房间）
`create_zone`	创建区域，可选择将其嵌套在父区域下

区域

工具	说明
`list_zones`	列出所有区域（房间/区域）及其层级结构

Flow

工具	说明
`list_flows`	列出简单 Flow 和高级 Flow，并显示启用/故障状态
`trigger_flow`	立即运行 Flow
`set_flow_enabled`	启用或禁用 Flow

Flow 创建

工具	说明
`get_flow`	按 ID 获取标准 WHEN/AND/THEN Flow 定义
`create_flow`	根据触发器/条件/操作创建标准 Flow
`update_flow`	更新标准 Flow 的字段
`delete_flow`	永久删除标准 Flow
`get_advanced_flow`	获取高级 Flow 定义（卡片、参数和连接）
`create_advanced_flow`	根据卡片图创建高级 Flow
`update_advanced_flow`	更新高级 Flow（替换卡片图）
`delete_advanced_flow`	永久删除高级 Flow

Flow 卡片发现

工具	说明
`list_flow_cards`	列出触发器/条件/操作卡片，可按子字符串筛选
`get_flow_card`	获取单个 Flow 卡片的完整定义和参数架构

逻辑与应用

工具	描述
`list_variables`	列出逻辑变量及其当前值
`set_variable`	设置逻辑变量的值
`list_apps`	列出已安装的应用及其版本、状态和来源
`restart_app`	重启 Homey 应用
`enable_app`	启用或禁用应用
`uninstall_app`	卸载应用并移除其设备

Insights 与能源

工具	描述
`list_insights`	列出可用的洞察日志
`get_insight_entries`	获取指定时间范围内的历史传感器／电表数据
`get_energy_live`	按区域和设备查看实时功耗
`get_energy_report`	查看日／周／月／年能源报告

天气、在家状态与位置

工具	描述
`get_weather`	获取 Homey 所在位置的当前天气
`get_weather_hourly`	获取逐小时天气预报
`get_presence`	查看所有用户的在家／离家及清醒／睡眠状态
`set_presence`	设置你自己的在家状态或睡眠状态
`get_location`	获取 Homey 配置的地理位置

闹钟与心情

工具	描述
`list_alarms`	列出所有闹钟和计时器
`set_alarm`	创建或更新闹钟
`delete_alarm`	删除闹钟
`list_moods`	列出各区域的心情（场景）
`set_mood`	在某个区域激活心情

通知

工具	描述
`list_notifications`	列出最近的 50 条通知
`create_notification`	向 Homey 时间线发送通知

网络诊断

工具	描述
`diagnose_zigbee_network`	Zigbee 网状网络健康状况、各节点最后上线时间、问题及修复建议
`diagnose_zwave_network`	Z-Wave 健康状况、传输失败、不可用节点及修复建议
`get_zwave_log`	获取近期 Z-Wave 网络原始日志以供故障排查

应用使用情况分析

工具	描述
`analyze_app_usage`	交叉核对应用与 RAM、设备及流引用，标记可考虑移除的应用（仅提供建议，只读）

系统与基础设施

工具	描述
`get_system_info`	系统信息（版本、Wi-Fi、主机名、硬件）
`list_drivers`	列出所有可用的设备驱动程序
`get_backup_status`	备份配置和上次备份时间
`create_backup`	安排新的备份
`get_ledring`	LED 灯环屏幕保护程序选项及当前设置
`set_ledring`	设置 LED 灯环屏幕保护程序
`get_updates`	检查系统更新和更新设置
`get_session`	当前 API 会话信息（用户、角色、范围）
`reboot_homey`	重启 Homey Pro
`get_memory_info`	按应用和组件查看内存使用情况
`get_storage_info`	存储空间使用情况明细
`set_system_name`	设置 Homey 系统名称

高级

工具	描述
`homey_api_call`	直接调用任意 Homey Web API 端点的原始入口

提示词

通过 MCP 提示词 API 访问的内置知识提示词：

提示词	描述
`homey_best_practices`	区域架构、设备命名、协议技巧、能源管理、安全
`homey_troubleshooting`	诊断离线设备、Z-Wave/Zigbee 问题、流调试、性能问题
`homey_flow_patterns`	自动化模式、命名约定、应避免的反模式

开发

npm run dev        # Run with tsx (no build step)
npm run build      # Compile TypeScript
npm run lint       # ESLint
npm run typecheck  # TypeScript strict check
npm start          # Run compiled version

技术栈

TypeScript + Node.js (>=20)
homey-api v3，官方 Homey Web API 客户端
@modelcontextprotocol/sdk v1.29，MCP 服务（使用 ToolAnnotations 注册工具）
zod，用于参数验证
supergateway，用于可自托管的流式 HTTP 传输

安全

依赖树、基础镜像和容器配置均使用 Trivy 和 npm audit 进行审计。发布的镜像在 node:22-alpine 上以非 root 用户运行，不包含预置密钥，生产依赖中没有高危或严重安全公告。完整审计、已接受的残余风险以及如何复现扫描，请参阅 SECURITY.md。

许可证

MIT

发布流程、一次性设置以及提交至 Unraid Community Applications 的说明见 PUBLISHING.md；重要变更见 CHANGELOG.md。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Homey-Wan-Kenobi MCP

关于 Homey-Wan-Kenobi MCP

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Homey-Wan-Kenobi MCP

为什么选择 Homey-Wan-Kenobi

实际能力深度

适合选择官方服务的情况

快速开始

身份验证

自托管（Docker / HTTP）

最快方式：一条命令（预构建镜像）

作为 MCP 客户端运行（stdio）

作为 HTTP 服务运行

Docker Compose

本地构建

连接客户端

工具

设备

设备和区域管理

区域

Flow

Flow 创建

Flow 卡片发现

逻辑与应用

Insights 与能源

天气、在家状态与位置

闹钟与心情

通知

网络诊断

应用使用情况分析

系统与基础设施

高级

提示词

开发

技术栈

安全

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？