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

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

Installation

1. Get Homey API Credentials

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

2. Find Your Homey ID

1. Open my.homey.app
2. Navigate to your Homey
3. 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:

1. List all flows via list_flows
2. Update each flow via update_flow
3. Verify the changes
4. Report any issues

Authentication

The server uses OAuth2 authentication via the Homey Cloud API:

1. On first run, it will authenticate using your Client ID/Secret
2. Token is cached for subsequent requests
3. 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:

• Web API Documentation
• Node.js API Reference

License

MIT

Author

Andy - Built for efficient Homey automation with AI agents

---

Sources:

• Flow - Homey Web API
• ManagerFlow - Homey Web API
• Homey Apps SDK Flow Guide