verdier/homey-mcp-server

Homey MCP Server

Homey Pro App exposing an MCP server over HTTP, enabling AI assistants like Claude to control your smart home.

🚀 Quick Setup

1. Install on Homey

git clone https://github.com/verdier/homey-mcp-server.git
cd homey-mcp-server
npm install
npm run install-homey

2. Get Your Authentication Token

You need a Homey Bearer Token for secure API access:

1. Login to my.homey.app
2. Go to Settings → API Key
3. Create a new API key with at least the homey.app scope

3. Configure Your AI Assistant

For Claude Desktop

Note: Claude Desktop does not currently support HTTP-based MCP servers directly. We use mcp-remote as a bridge to connect to this HTTP server.

Add to your configuration file with your Bearer token:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "homey": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://YOUR_HOMEY_IP/api/app/com.verdier.mcp-server/mcp",
        "--allow-http",
        "--header",
        "Authorization:Bearer YOUR_HOMEY_TOKEN"
      ]
    }
  }
}

Important: After updating the configuration:

1. Completely quit and reopen Claude Desktop for changes to take effect.
2. macOS users: On first launch, you may be prompted to allow Claude Desktop to find and communicate with devices on your local network. You must allow this permission and then restart Claude for the connection to work.

For VS Code

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "homey": {
      "type": "http",
      "url": "http://YOUR_HOMEY_IP/api/app/com.verdier.mcp-server/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_HOMEY_TOKEN"
      }
    }
  }
}

Note: Replace YOUR_HOMEY_IP with your Homey's actual IP address and YOUR_HOMEY_TOKEN with your extracted Bearer token.

4. Start Using

Ask your AI: "Turn on the living room lights" or "What's the temperature in the bedroom?"

📋 Requirements

• Homey Pro with local network access (Homey Cloud not supported)
• Node.js 16+ and Homey CLI: npm install -g homey
• Homey Bearer Token for authentication

🛠 Available Features

• Device Control: List, control, and query all Homey devices
• Zone Management: Filter devices by room/zone
• Flow Automation: List and view automation flow details
• Natural Language: Use conversational commands with AI assistants

⚠️ Known Limitations

• Flow Triggering: The trigger_flow tool is currently not operational due to Homey API cross app limitations.

🧪 Testing

Verify your installation with your Bearer token:

# Test MCP protocol
curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"initialize","id":1}' \
     "http://YOUR_HOMEY_IP/api/app/com.verdier.mcp-server/mcp"

🤝 Support

• Verify your Homey IP address is correct
• Ensure Homey Pro is on the same local network