javis/homey-mcp/UBUNTU_SETUP.md

Homey MCP Server - Ubuntu Setup Guide

Quick Start

1. Run the setup script

cd homey-mcp
chmod +x setup-ubuntu.sh run.sh run-lan.sh
./setup-ubuntu.sh

2. Configure your credentials

Edit the .env file with your Homey Pro credentials:

nano .env

Required fields:

• HOMEY_TOKEN - Your Homey Pro personal access token
• HOMEY_HOST - Your Homey Pro hub IP (e.g., 192.168.1.100)
• HOMEY_SCHEME / HOMEY_PORT - Local API protocol and port

Optional for LAN mode:

• HOMEY_MCP_AUTH_MODE - none for trusted-LAN compatibility, or bearer
• HOMEY_MCP_AUTH_TOKEN - Protects REST and, in bearer mode, MCP requests
• HOMEY_MCP_ADVERTISED_HOST - Set this to your server's LAN IP (e.g., 10.10.10.50). Required if using HOMEY_MCP_HOST=0.0.0.0: only requests whose Host header is this name, localhost or 127.0.0.1 are accepted (DNS-rebinding protection).
• HOMEY_MCP_ALLOWED_HOSTS - Extra comma-separated host names clients may use (e.g. a DNS name); * disables the check.

3. Start the server

For remote Odysseus client (LAN mode):

./run-lan.sh

For local stdio mode (Javis integration):

./run.sh

Manual Installation

If you prefer to set up manually:

# Install Python (if not installed)
sudo apt install python3.10 python3.venv build-essential libffi-dev libssl-dev

# Create virtual environment
cd homey-mcp
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -e .
pip install uvicorn

# Configure
cp .env.example .env
nano .env  # Edit with your credentials

# Run
HOMEY_MCP_TRANSPORT=streamable-http HOMEY_MCP_HOST=0.0.0.0 HOMEY_MCP_PORT=8080 \
    python -m homey_mcp

Persistent Operation with systemd

Install the service file for automatic startup:

# Copy service file (it is a template: one instance per user)
sudo cp homey-mcp.service /etc/systemd/system/homey-mcp@.service

# Reload systemd
sudo systemctl daemon-reload

# Enable and start (replace $USER with your username)
sudo systemctl enable --now homey-mcp@$USER.service

# Check status
sudo journalctl -u homey-mcp@$USER.service -f

Connecting Odysseus

To connect Odysseus as an MCP client, use the streamable-http transport:

1. Important: Before starting the server, set HOMEY_MCP_ADVERTISED_HOST in .env to your Ubuntu server's LAN IP address (e.g., 10.10.10.50). This is required for MCP Host header validation.
2. Ensure homey-mcp is running on port 8080 (or your configured port)
3. Configure Odysseus with the MCP endpoint:

   URL: http://<YOUR_UBUNTU_IP>:8080/mcp
   Transport: streamable-http
   Authentication: none
   

If you see a "421 Misdirected Request" error, the Host the client uses is not allowed: set HOMEY_MCP_ADVERTISED_HOST to the IP Odysseus connects to, or add the name to HOMEY_MCP_ALLOWED_HOSTS.

Use HOMEY_MCP_AUTH_MODE=none only on a trusted, firewall-restricted LAN. This avoids an OAuth discovery flow, which homey-mcp does not implement. If Odysseus supports a manually configured static Authorization header, you may instead set HOMEY_MCP_AUTH_MODE=bearer and configure the value of HOMEY_MCP_AUTH_TOKEN as its bearer token.

For Odysseus OpenAPI/app_api integration, import http://<YOUR_UBUNTU_IP>:8080/openapi.json and configure HOMEY_MCP_AUTH_TOKEN as a bearer token. REST routes remain protected even when MCP authentication is disabled.

Troubleshooting

Virtual environment issues

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Port already in use

# Check what's using the port
sudo lsof -i :8080

# Use a different port
HOMEY_MCP_PORT=8081 ./run-lan.sh

Permission denied

chmod +x run.sh run-lan.sh setup-ubuntu.sh

Check logs

sudo journalctl -u homey-mcp@$USER.service -f --since "1 hour ago"