🤖 AI Chat Control

1. Locate the Claude Desktop Config File

Easiest Method: Via Claude Desktop (recommended)

1. Open Claude Desktop
2. Go to File → Settings
3. Click on Developer in the left sidebar
4. Click the Edit Config button
5. This will open Windows Explorer (or Finder on macOS) with the config file selected
6. Open the file in a text editor (Notepad, VS Code, etc.)

Manual Method: Navigate to the file directly

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Get Your Configuration

Recommended: Use the App Settings Page

The easiest way to get the correct configuration is through the app's settings page:

1. In the Homey app, go to More → Apps
2. Find AI Chat Control and tap on it
3. Tap the Settings icon (gear icon)
4. Choose your configuration scenario:

5. Tap "Copy Configuration to Clipboard"
6. Paste the configuration into the Claude Desktop config file you opened in step 1

Alternative: Manual Configuration

If you prefer to configure manually, find your Homey's IP address:

1. Open the Homey app
2. Go to More → Settings → General → About
3. Under Connectivity, look for the Wi-Fi address

Then add this configuration to your Claude Desktop config file:

{
  "mcpServers": {
    "homey": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://[YOUR-HOMEY-IP]:3000/mcp",
        "--allow-http"
      ]
    }
  }
}

Replace [YOUR-HOMEY-IP] with your Homey's actual IP address (e.g., 192.168.1.50)

3. Restart Claude Desktop

1. Save the configuration file
2. Completely quit Claude Desktop
3. Important: Just closing the window is not enough - Claude continues running in the background. Use Task Manager (Windows) or Activity Monitor (macOS) to ensure Claude Desktop is fully closed.
4. Start Claude Desktop again

Step 1: Create the Flow

1. Open Homey and create a new Flow
2. Add the "AI Tool call" card as your trigger
3. Configure the card:
   • Command: play_radio
   • Description: Play a radio station on the kitchen radio
   • Parameters: (each parameter on its own line)

     streamUrl: string - Radio stream URL
     streamName: string - Name of the radio station

Step 2: Add Flow Actions

1. Add your "Cast Audio URL" action (or similar for your radio device)
2. For the stream URL field, use the token {{Parameter 1}} (this is the streamUrl parameter)
3. For the stream name field, use the token {{Parameter 2}} (this is the streamName parameter)
4. Add any other actions you want

Step 3: Refresh Claude's Flow List

After creating or modifying a Flow, ask Claude to refresh:

"Refresh the Homey flows"

Claude will use the refresh_homey_flows tool to discover your new Flow. Alternatively, you can restart Claude Desktop.

Step 4: Test with Claude

Ask Claude:

"Start radio station BBC1 on the kitchen radio"

Claude will parse this request and call the play_radio command with the appropriate URL and station name.

Check Network Connection

1. Verify your computer and Homey are on the same network
2. Try pinging your Homey: ping [homey-ip]
3. Make sure your firewall isn't blocking port 3000

Verify Configuration

1. Double-check the IP address in your Claude config
2. Ensure the format is exactly: http://[YOUR-HOMEY-IP]:3000/mcp
3. Make sure there are no typos in the JSON
4. Restart Claude Desktop after any config changes

Test the Connection

Open a browser and go to:

http://[YOUR-HOMEY-IP]:3000/health

You should see a JSON response with status information. If you get an error or timeout, the app may not be running.

This error means Claude Desktop can't find the npx command. This typically happens on macOS or Linux when Node.js isn't in the system PATH.

Quick Fix: Verify Node.js Installation

1. Open Terminal
2. Run these commands to verify Node.js is installed:

   node --version
   npm --version
   npx --version

3. If any command fails, install Node.js from nodejs.org

If Node.js is Installed but Error Persists

Option 1: Find the npx path and use it directly

1. In Terminal, run: which npx
2. Copy the full path (e.g., /usr/local/bin/npx or /opt/homebrew/bin/npx)
3. In your Claude config, replace "command": "npx" with the full path:

   {
     "mcpServers": {
       "homey": {
         "command": "/usr/local/bin/npx",
         "args": [
           "-y",
           "mcp-remote",
           "http://192.168.1.50:3000/mcp",
           "--allow-http"
         ]
       }
     }
   }

4. Save and restart Claude Desktop completely

Option 2: Install mcp-remote globally

1. In Terminal, run: npm install -g mcp-remote
2. Find where it was installed: which mcp-remote
3. Use the full path in your config:

   {
     "mcpServers": {
       "homey": {
         "command": "/usr/local/bin/mcp-remote",
         "args": [
           "http://192.168.1.50:3000/mcp",
           "--allow-http"
         ]
       }
     }
   }

4. Save and restart Claude Desktop completely

If Claude can see Homey tools but they fail when executed:

1. Verify the health endpoint works: http://[YOUR-HOMEY-IP]:3000/health
2. Check the detailed MCP server logs:

   Finding the MCP Server Log File

   macOS:

   1. Open Finder and press Cmd+Shift+G
   2. Paste: ~/Library/Application Support/Claude and press Enter
   3. Open the logs folder
   4. Look for mcp-server-homey.log
   5. Open it and scroll to the bottom for recent errors

   Windows:

   1. Press Win+R and type: %APPDATA%\Claude
   2. Open the logs folder
   3. Look for mcp-server-homey.log
   4. Open it and scroll to the bottom for recent errors

   💡 Tip: If the log file is very large and hard to read, delete it and restart Claude Desktop. Claude will create a fresh log file with only new entries, making it much easier to spot errors.

3. Look for specific error messages in the log file
4. Try restarting both the AI Chat Control app in Homey and Claude Desktop
5. Share the error messages in the forum for help if the issue persists