138 lines
3.8 KiB
Markdown
138 lines
3.8 KiB
Markdown
# Homey MCP Server - Ubuntu Setup Guide
|
|
|
|
## Quick Start
|
|
|
|
### 1. Run the setup script
|
|
```bash
|
|
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:
|
|
```bash
|
|
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):**
|
|
```bash
|
|
./run-lan.sh
|
|
```
|
|
|
|
**For local stdio mode (Javis integration):**
|
|
```bash
|
|
./run.sh
|
|
```
|
|
|
|
## Manual Installation
|
|
|
|
If you prefer to set up manually:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
rm -rf .venv
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e .
|
|
```
|
|
|
|
### Port already in use
|
|
```bash
|
|
# Check what's using the port
|
|
sudo lsof -i :8080
|
|
|
|
# Use a different port
|
|
HOMEY_MCP_PORT=8081 ./run-lan.sh
|
|
```
|
|
|
|
### Permission denied
|
|
```bash
|
|
chmod +x run.sh run-lan.sh setup-ubuntu.sh
|
|
```
|
|
|
|
### Check logs
|
|
```bash
|
|
sudo journalctl -u homey-mcp@$USER.service -f --since "1 hour ago" |