MCP Server for Homey API

A Model Context Protocol (MCP) server that enables AI agents (like Claude) to interact with your Homey home automation system.

🎯 Use Case

Perfect for bulk automation tasks like renaming 57 flows in minutes instead of hours! Use natural language with Claude to:

Batch rename flows according to naming conventions
Organize flows into folders
Enable/disable multiple flows at once
Trigger flows on schedule
Manage devices across zones

Features

Flow Management

✅ List all flows with filtering
✅ Get flow details
✅ Update flows (rename, enable/disable, move to folders)
✅ Trigger flows manually
✅ List flow folders

Device Management

✅ List all devices
✅ Filter devices by zone
✅ View device capabilities

Zone Management

✅ List all zones in hierarchical structure

Prerequisites

Homey Pro with cloud access
Homey Developer Account - Create at https://tools.developer.homey.app/
Node.js 18+

Installation

1. Get Homey API Credentials

Go to Homey Developer Tools
Click "Create App"
Fill in:
- App Name: "MCP Server" (or any name)
- Redirect URL: http://localhost:8080 (not used, but required)
Save and note your Client ID and Client Secret

2. Find Your Homey ID

Open my.homey.app
Navigate to your Homey
Copy the ID from the URL: https://my.homey.app/homeys/YOUR_HOMEY_ID/flows

3. Install Dependencies

cd mcp-server-homey
npm install

4. Configure Environment

cp .env.example .env

Edit .env and add your credentials:

HOMEY_CLIENT_ID=your_client_id_here
HOMEY_CLIENT_SECRET=your_client_secret_here
HOMEY_ID=your_homey_id_here

5. Build

npm run build

Usage

Standalone Mode (for testing)

npm start

The server will run on stdio and wait for MCP protocol messages.

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "homey": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-server-homey/build/index.js"
      ],
      "env": {
        "HOMEY_CLIENT_ID": "your_client_id",
        "HOMEY_CLIENT_SECRET": "your_client_secret",
        "HOMEY_ID": "your_homey_id"
      }
    }
  }
}

Or use the installed package:

{
  "mcpServers": {
    "homey": {
      "command": "mcp-server-homey"
    }
  }
}

(Make sure .env file is in the correct location)

Available Tools

Flow Tools

`list_flows`

List all Homey flows with optional filtering.

{
  "folder": "binnen/begane grond",  // Optional: filter by folder
  "enabled": true                    // Optional: filter by enabled status
}

`get_flow`

Get detailed information about a specific flow.

{
  "id": "flow-id-here"
}

`update_flow`

Update a flow (rename, enable/disable, move to folder).

{
  "id": "flow-id-here",
  "name": "new flow name",    // Optional
  "enabled": true,             // Optional
  "folder": "folder-id-here"   // Optional
}

Example - Rename a flow:

{
  "id": "271b8359-7835-434c-bd65-05c3b88da8bf",
  "name": "wz_comfort_blokkeren"
}

`list_flow_folders`

List all flow folders in hierarchical structure.

{}

`trigger_flow`

Manually trigger a flow.

{
  "id": "flow-id-here"
}

Device Tools

`list_devices`

List all Homey devices.

{
  "zone": "woonkamer"  // Optional: filter by zone name
}

Zone Tools

`list_zones`

List all Homey zones in hierarchical structure.

{}

Example Usage with Claude

Once configured in Claude Desktop, you can ask:

"List all my Homey flows"

"Rename the flow 'WK: activity' to 'wk: activity'"

"Show me all flows in the binnen/begane grond folder"

"Update all flows starting with 'WZ_' to lowercase"

Use Case: Batch Flow Renaming

Perfect for the flow naming convention migration! You can ask Claude:

"I have 57 flows that need to be renamed according to a new naming convention. Here's the mapping: [paste migration guide]. Please rename all flows using the Homey MCP server."

Claude will:

List all flows via list_flows
Update each flow via update_flow
Verify the changes
Report any issues

Authentication

The server uses OAuth2 authentication via the Homey Cloud API:

On first run, it will authenticate using your Client ID/Secret
Token is cached for subsequent requests
No manual login required once configured

Security Notes

Keep your .env file secure - it contains API credentials
Don't commit .env to version control (already in .gitignore)
Client Secret should be treated as a password

Troubleshooting

"HOMEY_CLIENT_ID must be set"

Make sure .env file exists and contains your credentials.

"Failed to authenticate"

Check that:

Client ID and Secret are correct
Homey ID is correct (from URL)
You have internet connection to Homey Cloud

"Flow not found"

Flow ID must be exact. Use list_flows to find the correct ID.

Development

Watch Mode

npm run watch

Run Without Building

npm run dev

API Reference

This MCP server wraps the Homey Web API:

License

MIT

Author

Andy - Built for efficient Homey automation with AI agents

Sources: