# MCP Server for Homey API

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-0.5-orange)](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)