# MCP Server for Homey API
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
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/](https://tools.developer.homey.app/)
3. **Node.js 18+**
## Installation
### 1. Get Homey API Credentials
1. Go to [Homey Developer Tools](https://tools.developer.homey.app/)
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](https://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
```bash
cd mcp-server-homey
npm install
```
### 4. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` and add your credentials:
```env
HOMEY_CLIENT_ID=your_client_id_here
HOMEY_CLIENT_SECRET=your_client_secret_here
HOMEY_ID=your_homey_id_here
```
### 5. Build
```bash
npm run build
```
## Usage
### Standalone Mode (for testing)
```bash
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`):
```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:**
```json
{
"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.
```json
{
"folder": "binnen/begane grond", // Optional: filter by folder
"enabled": true // Optional: filter by enabled status
}
```
#### `get_flow`
Get detailed information about a specific flow.
```json
{
"id": "flow-id-here"
}
```
#### `update_flow`
Update a flow (rename, enable/disable, move to folder).
```json
{
"id": "flow-id-here",
"name": "new flow name", // Optional
"enabled": true, // Optional
"folder": "folder-id-here" // Optional
}
```
**Example - Rename a flow:**
```json
{
"id": "271b8359-7835-434c-bd65-05c3b88da8bf",
"name": "wz_comfort_blokkeren"
}
```
#### `list_flow_folders`
List all flow folders in hierarchical structure.
```json
{}
```
#### `trigger_flow`
Manually trigger a flow.
```json
{
"id": "flow-id-here"
}
```
### Device Tools
#### `list_devices`
List all Homey devices.
```json
{
"zone": "woonkamer" // Optional: filter by zone name
}
```
### Zone Tools
#### `list_zones`
List all Homey zones in hierarchical structure.
```json
{}
```
## 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
```bash
npm run watch
```
### Run Without Building
```bash
npm run dev
```
## API Reference
This MCP server wraps the [Homey Web API](https://api.developer.homey.app/):
- [Web API Documentation](https://api.developer.homey.app/)
- [Node.js API Reference](https://athombv.github.io/node-homey-api/)
## License
MIT
## Author
Andy - Built for efficient Homey automation with AI agents
---
**Sources:**
- [Flow - Homey Web API](https://athombv.github.io/node-homey-api/HomeyAPIV2.ManagerFlow.Flow.html)
- [ManagerFlow - Homey Web API](https://athombv.github.io/node-homey-api/HomeyAPIV2.ManagerFlow.html)
- [Homey Apps SDK Flow Guide](https://apps.developer.homey.app/the-basics/flow)
