{
  "markdown": "# Homey-Wan-Kenobi MCP\n\n[![CI](https://github.com/Ringosystems/Homey-Wan-Kenobi-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Ringosystems/Homey-Wan-Kenobi-MCP/actions/workflows/ci.yml)\n[![Docker Pulls](https://img.shields.io/docker/pulls/ringosystems/homey-wan-kenobi)](https://hub.docker.com/r/ringosystems/homey-wan-kenobi)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nMCP server for controlling [Homey Pro](https://homey.app/) smart home systems through the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n> The name nods to Obi-Wan Kenobi, your home's only hope for natural-language control.\n\n60 tools and 3 knowledge prompts for device control, flow authoring, automation, monitoring, troubleshooting, network diagnostics, and self-hosted deployment.\n\n## Why Homey-Wan-Kenobi\n\nAthom ships an official [Homey MCP Server](https://mcp.athom.com): a cloud-brokered remote connector you add to a paid Claude or ChatGPT plan and sign into with your Homey account. It covers device status and control, renaming and moving devices, creating, updating and starting Flows and Advanced Flows, and setting Moods.\n\nThis server differs in two ways. It is **self-hosted**, so you run it yourself over stdio or streamable-HTTP with no third-party broker and no paid AI-plan requirement. And it adds **operational depth** for power users that is not part of the official server's described capabilities.\n\nThe table reflects Athom's publicly described capabilities as of June 2026. Athom does not publish a formal tool list, so the right-hand gaps are inferred from their documentation, not stated by Athom.\n\n| Capability | Official Homey MCP (`mcp.athom.com`) | Homey-Wan-Kenobi |\n|------------|--------------------------------------|------------------|\n| Hosting | Cloud-brokered remote connector | Self-hosted, stdio or HTTP, no broker |\n| Access | Paid Claude/ChatGPT connector plan | Any MCP client, no plan requirement |\n| Devices, zones, control, rename, move | Yes | Yes |\n| Flow and Advanced Flow authoring | Yes | Yes |\n| Moods | Yes | Yes |\n| Flow-card schema discovery (build flows from scratch) | Not described | Yes |\n| Energy: live power and day/week/month/year reports | Not described | Yes |\n| Insights: historical sensor and meter data | Not described | Yes |\n| Z-Wave and Zigbee mesh diagnostics with remediations | Not described | Yes |\n| App memory and usage analysis (removal candidates) | Not described | Yes |\n| Infrastructure ops: backups, reboot, updates, memory, storage | Not described | Yes |\n| Raw Homey Web API passthrough | Not described | Yes |\n| Listed in the public MCP Registry | No | Yes |\n\n### The depth, in practice\n\n- **Network diagnostics that the official server does not describe.** `diagnose_zwave_network` and `diagnose_zigbee_network` read controller health, grade each node by last-seen age (battery-sleep aware), group transmit failures, correlate them with unavailable devices, and return severity-ranked remediations. `get_zwave_log` exposes the raw network log.\n- **Energy and Insights analysis.** Live power by zone and device, day/week/month/year energy reports, and timestamped historical sensor and meter data, so the model can answer \"what is using power right now\" or \"how has the bedroom temperature trended this week\".\n- **App memory and usage analysis.** `analyze_app_usage` cross-references every app against RAM, device counts and flow references to flag safe removal candidates and estimate savings. Read-only and advisory.\n- **Build automations from scratch.** A flow-card discovery engine (`list_flow_cards`, `get_flow_card`) returns each card's full argument schema, and full standard and Advanced Flow CRUD (including delete) lets an AI author and tear down the whole cards graph by UUID.\n- **Infrastructure operations from one interface.** Backups, reboot, update checks, memory and storage usage, drivers, LED ring, session and location info.\n- **A future-proof escape hatch.** `homey_api_call` reaches any Homey Web API endpoint directly, so new firmware features work without waiting for a tool update.\n\nIt runs on a hardened, non-root `node:22-alpine` image whose every build and release is gated on a Trivy scan, and it is published to Docker Hub, GHCR and the public MCP Registry. See [the tool reference](#tools) below for the full list.\n\n### When the official server is the better fit\n\nThis server is local-first and self-hosted, which is both its strength and its trade-off. The official Homey MCP is the easier choice when you want:\n\n- **Zero setup and managed hosting.** Add one URL and sign in with your Homey account. There is no container to run, expose, or maintain, and there is a one-click ChatGPT app.\n- **Secure remote access from anywhere.** Athom brokers the connection through its cloud, so it works away from home without exposing anything on your LAN. This server's HTTP mode is intended for a trusted local network; remote use is your own VPN or authenticated reverse proxy.\n- **Every Homey model.** The official endpoint reaches Homey Cloud, Pro, Pro mini and Self-Hosted Server, including cloud-only setups that have no local API. This server targets a Homey reachable over its local API or your Athom token, so it is happiest with a Homey Pro.\n- **First-party support.** It is maintained by Athom, kept in step with firmware, and officially tested with Claude and the ChatGPT app. This project is independent and best-effort.\n\nThe two are complementary. Many people use the official connector for quick remote control and this server for the deep local diagnostics, energy analysis, and infrastructure work. Athom does not publish a formal tool list, so the official server may also include capabilities not reflected above.\n\n## Quick Start\n\n```bash\ngit clone https://github.com/Ringosystems/Homey-Wan-Kenobi-MCP.git\ncd Homey-Wan-Kenobi-MCP\nnpm install\nnpm run build\n```\n\nAuthenticate with your Homey:\n\n```bash\nnpx homey login\nnpx homey select\n```\n\nAdd to your MCP client config (Kiro, Claude Desktop, Cline, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"homey\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/Homey-Wan-Kenobi-MCP/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Authentication\n\nThe server supports two authentication methods:\n\n**Homey CLI (recommended)** runs `npx homey login` and `npx homey select`. The server reads the stored OAuth token from `~/.athom-cli/settings.json` automatically.\n\n**Local API Key** is created at [my.homey.app](https://my.homey.app/settings/system/api-keys). Set environment variables:\n\n```bash\nexport HOMEY_ADDRESS=http://192.168.1.x\nexport HOMEY_TOKEN=your-api-key\n```\n\nThe local API key method is the recommended choice when running self-hosted in a container, since it does not depend on a mounted CLI settings file.\n\n## Self-Hosted (Docker / HTTP)\n\nThe image is published at [`ringosystems/homey-wan-kenobi`](https://hub.docker.com/r/ringosystems/homey-wan-kenobi) (mirrored to `ghcr.io/ringosystems/homey-wan-kenobi`), and the server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.Ringosystems/homey-wan-kenobi-mcp`. It is built on `node:22-alpine`, runs as a non-root user, and ships no baked-in secrets. See [SECURITY.md](SECURITY.md) for the audit details.\n\nIt defaults to the **stdio** transport so an MCP client can launch it directly, and exposes a long-lived **streamable-HTTP** service (via [supergateway](https://github.com/supercorp-ai/supergateway) at `/mcp`, health at `/healthz`) when you set `MCP_TRANSPORT=streamable-http`.\n\n### Fastest: one command (prebuilt image)\n\nNo clone or build. Pull two things and start it:\n\n```bash\ncurl -fsSLO https://raw.githubusercontent.com/Ringosystems/Homey-Wan-Kenobi-MCP/main/docker-compose.deploy.yml\nprintf 'HOMEY_ADDRESS=http://192.168.1.x\\nHOMEY_TOKEN=your-local-api-key\\n' > .env\ndocker compose -f docker-compose.deploy.yml up -d\n```\n\nThe service is then at `http://<host>:8000/mcp` (health at `/healthz`). On **Unraid**, add the template by URL instead: Docker, Add Container, paste `https://raw.githubusercontent.com/Ringosystems/Homey-Wan-Kenobi-MCP/main/deploy/unraid/homey-wan-kenobi.xml` into the Template field. The image is multi-arch, so it runs on x86 and ARM (Apple Silicon, Raspberry Pi) hosts.\n\n> The `/mcp` endpoint has no built-in authentication. Keep it on a trusted LAN or behind a reverse proxy that adds TLS and auth.\n\n### Run as an MCP client (stdio)\n\n```bash\ndocker run -i --rm \\\n  -e HOMEY_ADDRESS=http://192.168.1.x \\\n  -e HOMEY_TOKEN=your-local-api-key \\\n  ringosystems/homey-wan-kenobi:latest\n```\n\n### Run as an HTTP service\n\n```bash\ndocker run -d -p 8000:8000 \\\n  -e MCP_TRANSPORT=streamable-http \\\n  -e HOMEY_ADDRESS=http://192.168.1.x \\\n  -e HOMEY_TOKEN=your-local-api-key \\\n  --restart unless-stopped \\\n  ringosystems/homey-wan-kenobi:latest\n```\n\n### Docker Compose\n\nSupply your Homey credentials via a `.env` file next to `docker-compose.yml`:\n\n```bash\ncat > .env <<'EOF'\nHOMEY_ADDRESS=http://192.168.1.x\nHOMEY_TOKEN=your-local-api-key\nEOF\n\n# Pull the published image, or add --build to build locally instead\ndocker compose up -d\n```\n\nThe provided `docker-compose.yml` references the published image (with `build: .` as a local-build fallback) and applies container hardening (read-only root filesystem, dropped Linux capabilities, `no-new-privileges`, and memory/PID limits):\n\n```yaml\nservices:\n  homey-wan-kenobi:\n    image: ringosystems/homey-wan-kenobi:latest\n    build: .\n    container_name: homey-wan-kenobi\n    ports:\n      - \"8000:8000\"\n    environment:\n      MCP_TRANSPORT: streamable-http\n      HOMEY_ADDRESS: \"${HOMEY_ADDRESS:-http://192.168.1.x}\"\n      HOMEY_TOKEN: \"${HOMEY_TOKEN:-}\"\n    restart: unless-stopped\n    read_only: true\n    tmpfs:\n      - /tmp\n    security_opt:\n      - no-new-privileges:true\n    cap_drop:\n      - ALL\n    mem_limit: 256m\n    pids_limit: 128\n    healthcheck:\n      test: [\"CMD\", \"node\", \"-e\", \"fetch('http://localhost:8000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\"]\n      interval: 30s\n      timeout: 5s\n      retries: 3\n      start_period: 20s\n```\n\n### Build locally\n\n```bash\ndocker build -t ringosystems/homey-wan-kenobi .\ndocker run -d -p 8000:8000 \\\n  -e MCP_TRANSPORT=streamable-http \\\n  -e HOMEY_ADDRESS=http://192.168.1.x \\\n  -e HOMEY_TOKEN=your-local-api-key \\\n  --restart unless-stopped \\\n  ringosystems/homey-wan-kenobi\n```\n\n### Connecting a client\n\nPoint an MCP client at the streamable-HTTP endpoint:\n\n```json\n{\n  \"mcpServers\": {\n    \"homey\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://your-host:8000/mcp\"\n    }\n  }\n}\n```\n\nCheck health with `curl http://your-host:8000/healthz`.\n\n## Tools\n\n### Devices\n\n| Tool | Description |\n|------|-------------|\n| `list_devices` | List devices with live capability values, filter by zone or class |\n| `get_device` | Get full device details and all capability values by ID |\n| `search_devices` | Search devices by name, class, or capability |\n| `set_device_capability` | Control a device (onoff, dim, target_temperature, volume_set, etc.) |\n\n### Device & Zone Management\n\n| Tool | Description |\n|------|-------------|\n| `rename_device` | Rename a device |\n| `move_device_to_zone` | Move a device to a different zone (room) |\n| `create_zone` | Create a new zone, optionally nested under a parent |\n\n### Zones\n\n| Tool | Description |\n|------|-------------|\n| `list_zones` | List all zones (rooms/areas) with their hierarchy |\n\n### Flows\n\n| Tool | Description |\n|------|-------------|\n| `list_flows` | List simple and advanced flows with enabled/broken status |\n| `trigger_flow` | Run a flow immediately |\n| `set_flow_enabled` | Enable or disable a flow |\n\n### Flow Authoring\n\n| Tool | Description |\n|------|-------------|\n| `get_flow` | Get a standard WHEN/AND/THEN flow definition by ID |\n| `create_flow` | Create a standard flow from trigger/conditions/actions |\n| `update_flow` | Update fields of a standard flow |\n| `delete_flow` | Permanently delete a standard flow |\n| `get_advanced_flow` | Get an Advanced Flow definition (cards, args, connections) |\n| `create_advanced_flow` | Create an Advanced Flow from a cards graph |\n| `update_advanced_flow` | Update an Advanced Flow (replaces the cards graph) |\n| `delete_advanced_flow` | Permanently delete an Advanced Flow |\n\n### Flow Card Discovery\n\n| Tool | Description |\n|------|-------------|\n| `list_flow_cards` | List trigger/condition/action cards, filtered by substring |\n| `get_flow_card` | Get one flow card's full definition and argument schema |\n\n### Logic & Apps\n\n| Tool | Description |\n|------|-------------|\n| `list_variables` | List logic variables with current values |\n| `set_variable` | Set a logic variable value |\n| `list_apps` | List installed apps with version, status, and origin |\n| `restart_app` | Restart a Homey app |\n| `enable_app` | Enable or disable an app |\n| `uninstall_app` | Uninstall an app and remove its devices |\n\n### Insights & Energy\n\n| Tool | Description |\n|------|-------------|\n| `list_insights` | List available insight logs |\n| `get_insight_entries` | Get historical sensor/meter data over a time range |\n| `get_energy_live` | Live power consumption by zone and device |\n| `get_energy_report` | Energy report for day/week/month/year |\n\n### Weather, Presence & Location\n\n| Tool | Description |\n|------|-------------|\n| `get_weather` | Current weather at Homey's location |\n| `get_weather_hourly` | Hourly weather forecast |\n| `get_presence` | Home/away and awake/asleep status for all users |\n| `set_presence` | Set your own presence or sleep state |\n| `get_location` | Homey's configured geographic location |\n\n### Alarms & Moods\n\n| Tool | Description |\n|------|-------------|\n| `list_alarms` | List all alarms and timers |\n| `set_alarm` | Create or update an alarm |\n| `delete_alarm` | Delete an alarm |\n| `list_moods` | List moods (scenes) per zone |\n| `set_mood` | Activate a mood in a zone |\n\n### Notifications\n\n| Tool | Description |\n|------|-------------|\n| `list_notifications` | List the 50 most recent notifications |\n| `create_notification` | Send a notification to the Homey timeline |\n\n### Network Diagnostics\n\n| Tool | Description |\n|------|-------------|\n| `diagnose_zigbee_network` | Zigbee mesh health, per-node last-seen, issues and remediations |\n| `diagnose_zwave_network` | Z-Wave health, transmit failures, unavailable nodes, remediations |\n| `get_zwave_log` | Raw recent Z-Wave network log for troubleshooting |\n\n### App Usage Analysis\n\n| Tool | Description |\n|------|-------------|\n| `analyze_app_usage` | Cross-reference apps against RAM, devices, and flow references to flag removal candidates (advisory, read-only) |\n\n### System & Infrastructure\n\n| Tool | Description |\n|------|-------------|\n| `get_system_info` | System info (version, wifi, hostname, hardware) |\n| `list_drivers` | List all available device drivers |\n| `get_backup_status` | Backup config and last backup time |\n| `create_backup` | Schedule a new backup |\n| `get_ledring` | LED ring screensaver options and current setting |\n| `set_ledring` | Set the LED ring screensaver |\n| `get_updates` | Check for system updates and update settings |\n| `get_session` | Current API session info (user, role, scopes) |\n| `reboot_homey` | Reboot the Homey Pro |\n| `get_memory_info` | Memory usage by app and component |\n| `get_storage_info` | Storage usage breakdown |\n| `set_system_name` | Set the Homey system name |\n\n### Advanced\n\n| Tool | Description |\n|------|-------------|\n| `homey_api_call` | Raw escape hatch to call any Homey Web API endpoint directly |\n\n## Prompts\n\nBuilt-in knowledge prompts accessible via the MCP prompts API:\n\n| Prompt | Description |\n|--------|-------------|\n| `homey_best_practices` | Zone architecture, device naming, protocol tips, energy management, security |\n| `homey_troubleshooting` | Diagnosing offline devices, Z-Wave/Zigbee issues, flow debugging, performance |\n| `homey_flow_patterns` | Automation patterns, naming conventions, anti-patterns to avoid |\n\n## Development\n\n```bash\nnpm run dev        # Run with tsx (no build step)\nnpm run build      # Compile TypeScript\nnpm run lint       # ESLint\nnpm run typecheck  # TypeScript strict check\nnpm start          # Run compiled version\n```\n\n## Tech Stack\n\n- TypeScript + Node.js (>=20)\n- [homey-api](https://www.npmjs.com/package/homey-api) v3, the official Homey Web API client\n- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) v1.29, MCP server (`registerTool` with `ToolAnnotations`)\n- [zod](https://www.npmjs.com/package/zod) for parameter validation\n- [supergateway](https://github.com/supercorp-ai/supergateway) for the self-hosted streamable-HTTP transport\n\n## Security\n\nThe dependency tree, base image, and container configuration are audited with [Trivy](https://trivy.dev/) and `npm audit`. The published image runs as a non-root user on `node:22-alpine` with no baked-in secrets, and the production dependencies ship with 0 high or critical advisories. See [SECURITY.md](SECURITY.md) for the full audit, accepted residual risks, and how to reproduce the scans.\n\n## License\n\n[MIT](LICENSE)\n\nRelease process, one-time setup, and Unraid Community Applications submission are\ndocumented in [PUBLISHING.md](PUBLISHING.md); notable changes in\n[CHANGELOG.md](CHANGELOG.md).\n",
  "bytes": 17321,
  "sha": "b0e6e6c5f112f131c1e57cf5deb5e83661d7ec952759582e7788395c90e83699",
  "repo_slug": "ringosystems/homey-wan-kenobi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ringosystems_homey_wan_kenobi__0d19ae05/readme"
}