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

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

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

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

• ✅ List all zones in hierarchical structure

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

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

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

cd mcp-server-homey
npm install

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

npm run build

npm start

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

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)

List all Homey flows with optional filtering.

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

Get detailed information about a specific flow.

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

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 all flow folders in hierarchical structure.

{}

Manually trigger a flow.

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

List all Homey devices.

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

List all Homey zones in hierarchical structure.

{}

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"

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

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

• 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

Make sure .env file exists and contains your credentials.

Check that:

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

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

npm run watch

npm run dev

This MCP server wraps the Homey Web API:

• Web API Documentation
• Node.js API Reference

MIT

Andy - Built for efficient Homey automation with AI agents

Sources:

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