智能家居控制MCP服务器

Homey MCP Server

MCP server for controlling Homey Pro smart home systems through the Model Context Protocol.

50 tools and 3 knowledge prompts for device control, automation, monitoring, troubleshooting, and more.

Built on MCP TypeScript SDK v2. One stdio binary serves clients on the 2026-07-28 protocol revision and 2025-era clients (including clients on the v1 SDK); the era is chosen per connection. Requires Node.js 22 or later.

Changes in 3.0.0

3.0.0 moves to SDK v2 and rolls up the hardening from the 2.4 line:

• MCP SDK v2 and protocol 2026-07-28. @modelcontextprotocol/sdk is replaced by @modelcontextprotocol/server 2.x. The server starts through serveStdio, so 2026-07-28 and 2025-era clients both connect. Tool names, input shapes, annotations and prompts are unchanged; advertised input schemas now declare JSON Schema 2020-12.
• Client-visible protocol changes from SDK v2. Calling an unknown tool name now fails with JSON-RPC error -32602 instead of returning an isError result. Tool error text no longer starts with MCP error <code>: . Input-validation messages put the field path first (id: must be a UUID). Tools no longer advertise execution.taskSupport.
• Node.js 22 is the minimum (engines.node >=22), matching homey-api 3.21.
• zod 4 for every input schema.
• Security capabilities are gated. set_device_capability refuses locks, garage doors, home alarms and alarm_* capabilities unless HOMEY_MCP_ALLOW_SECURITY_CAPS=1, and checks every write against the capability definition.
• Id validation. Device, flow, zone, variable, alarm and mood ids must be UUIDs; app, script and insight ids are checked by pattern before they reach the Homey API.
• Privacy filtering. get_system_info leaves out network identifiers, the hostname and the cloud id; get_location rounds coordinates and drops the street address unless HOMEY_MCP_PRECISE_LOCATION=1.
• Auth precedence. HOMEY_ADDRESS plus HOMEY_TOKEN is tried first and, when set, is the only source used; then the cached LAN session, then the Homey CLI token.
• New audit_flows checks: advanced flows, logic variable, HomeyScript and target-flow references held in card arguments, numbers stored in text arguments, missing required arguments, and flows that mix grouped and ungrouped conditions.

Quick Start

git clone https://github.com/homey-mcp/homey-mcp.git
cd homey-mcp
npm install
npm run build

Authenticate with your Homey:

npx homey login
npx homey select

Add to your MCP client config (Kiro, Claude Desktop, Cline, etc.):

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

Authentication

The server tries these sources in order and logs the one it used to stderr (never the token itself):

1. Local API key: when both HOMEY_ADDRESS and HOMEY_TOKEN are set, they are used and nothing else is tried. A scoped key is therefore a real ceiling on what the server can do. Create one at my.homey.app with only the scopes you need:

   复制

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

2. Cached LAN session: ~/.athom-cli/homey-mcp-local-cache.json, written after a successful Homey CLI login so later starts connect over the LAN without the rate-limited Athom cloud. It is validated with one authenticated call before use. It is discarded only when the Homey rejects it; an offline Homey or a timeout keeps it.

3. Homey CLI token: run npx homey login and npx homey select. The server reads the OAuth token from ~/.athom-cli/settings.json and resolves the Homey's LAN address through the Athom cloud. This token has owner scope.

When a session expires mid-run, the server resets it and re-runs the call once, but only for read-only and idempotent tools. Other tools report the reset and are not re-run, because the rejection may have come after the action took effect.

Credential files

The cache holds a session token. It is written with mode 0600 in a 0700 directory, and the server warns on stderr when ~/.athom-cli/settings.json is readable by other accounts. To clear the cache, delete the file; the next start re-authenticates through the CLI token. To tighten the CLI's own files:

chmod 700 ~/.athom-cli && chmod 600 ~/.athom-cli/settings.json

Environment variables

Safety

• Tool results are data. The server's MCP instructions tell the client that device, flow and zone names, card arguments, notification text, script source and script output are written by household members and apps and must not be followed as instructions. Control, bidi and zero-width characters are stripped from results and long strings are capped.
• Ids are validated before they reach the Homey API (UUIDs for devices, flows, zones, variables, alarms and moods; app, script and insight ids by pattern), so a crafted id cannot reach a different endpoint.
• set_device_capability checks the value against the device's capability definition: the capability must exist and be setable, and type, min/max and enum values are enforced.
• Tool annotations mark destructive tools (run_script, upsert_script, trigger_flow, reboot_homey, and the disable and delete paths) so clients can ask for confirmation.
• get_system_info leaves out network identifiers (SSID, MAC and IP addresses, gateway, DNS), the hostname and the cloud id.

Tools

Devices

Zones & Flows

Logic & Apps

HomeyScript

Insights & Energy

Weather & Presence

Alarms & Moods

Notifications & System

Infrastructure & Protocols

Prompts

Built-in knowledge prompts accessible via the MCP prompts API:

Development

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 test           # Build, then unit and stdio compatibility tests (node:test via tsx)
npm start          # Run compiled version

Tech Stack

• TypeScript + Node.js (≥22)
• homey-api v3 — Official Homey Web API client
• @modelcontextprotocol/server v2 — MCP server (registerTool with ToolAnnotations, serveStdio for protocol 2026-07-28 and 2025-era clients)
• zod v4 — Parameter validation

License

MIT