# Hubitat MCP Server

A TypeScript [MCP](https://modelcontextprotocol.io) server that lets Claude control your [Hubitat Elevation](https://hubitat.com) smart home hub. Works with Claude Code (CLI + mobile), Claude Desktop, and Claude.ai.

## Features

- **12 MCP tools** — Control devices, modes, HSM, and hub variables
- **Remote access** — Built-in [ngrok](https://ngrok.com) tunnel for access from anywhere
- **Dual transport** — stdio (local) + Streamable HTTP (remote)
- **Auto-generated home context** — Claude knows your devices by name
- **Device aliasing** — Say "kitchen light" instead of device ID 42
- **Health endpoint** — Monitor hub connectivity and tunnel status
- **Cross-platform** — macOS, Raspberry Pi, Docker

## Quick Start

**macOS:**
```bash
brew install node@22 git
git clone https://github.com/rfhayn/hubitat-mcp-server.git
cd hubitat-mcp-server
./setup.sh
```

**Raspberry Pi / Linux:**
```bash
sudo apt update && sudo apt install -y git
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
git clone https://github.com/rfhayn/hubitat-mcp-server.git
cd hubitat-mcp-server
./setup.sh
```

The setup script walks you through everything: Hubitat credentials, ngrok configuration, and Claude integration.

## Prerequisites

### 1. Node.js 20+ and Git

**macOS:**
```bash
brew install node@22 git
```

**Raspberry Pi / Linux:**
```bash
sudo apt update && sudo apt install -y git
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
```

### 2. Hubitat Maker API

You need to enable the Maker API on your Hubitat hub:

1. Open your Hubitat admin interface at `http://<hub-ip>`
2. Go to **Apps** → **Add Built-in App** → **Maker API**
3. Select the devices you want Claude to control
4. Check **"Allow control of modes"**
5. Check **"Allow control of HSM"** (if you use Hubitat Safety Monitor)
6. Optionally add hub variables under **"Allow endpoint to control these hub variables"**
7. Click **Done** and note the **App ID** and **Access Token** displayed on the app page

### 3. ngrok Account (for remote access)

If you want to use Claude from your phone or claude.ai (not just local CLI):

1. Sign up free at [ngrok.com](https://dashboard.ngrok.com/signup)
2. Copy your **authtoken** from [dashboard](https://dashboard.ngrok.com/authtokens)
3. Claim a free **static domain** from [domains](https://dashboard.ngrok.com/domains) (e.g., `your-name.ngrok-free.app`)

## Manual Setup

If you prefer not to use the setup script:

```bash
# Install and build
npm install
npm run build

# Configure
cp .env.example .env
# Edit .env with your Hubitat and ngrok credentials

# Run
npm start
```

## Configuration

All configuration is in `.env`:

```env
# Hubitat Connection
HUBITAT_HOST=192.168.1.100      # Your hub's IP address
HUBITAT_APP_ID=42                # Maker API app ID
HUBITAT_ACCESS_TOKEN=xxx         # Maker API access token

# MCP Server
MCP_TRANSPORT=http               # "stdio" or "http"
MCP_HTTP_PORT=3000               # Port for HTTP transport
MCP_AUTH_TOKEN=xxx               # Bearer token (auto-generated by setup)

# ngrok (optional)
NGROK_AUTHTOKEN=xxx              # From ngrok dashboard
NGROK_DOMAIN=you.ngrok-free.app  # Free static domain
```

## Connecting Claude

After starting the server, connect Claude using one of these methods:

### Claude Code (CLI)

```bash
claude mcp add hubitat --transport http https://you.ngrok-free.app/mcp \
  --header "Authorization: Bearer YOUR_AUTH_TOKEN"
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hubitat": {
      "type": "url",
      "url": "https://you.ngrok-free.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}
```

### Claude.ai (Web)

Go to **Settings** → **Connectors** → **Add MCP Server** and paste your MCP URL.

### Local stdio (no remote access needed)

```bash
claude mcp add hubitat --transport stdio -- node /path/to/hubitat-mcp-server/dist/index.js
```

## Available Tools

| Tool | Description |
|------|-------------|
| `list_devices` | List all authorized devices |
| `get_device` | Get device details (attributes, capabilities, commands) |
| `send_command` | Send a command to a device (on, off, setLevel, lock, etc.) |
| `get_device_events` | Get recent event history for a device |
| `get_modes` | List available hub modes |
| `get_current_mode` | Get the currently active mode |
| `set_mode` | Change the hub mode |
| `get_hsm_status` | Get HSM arm/disarm status |
| `set_hsm` | Arm or disarm HSM |
| `get_variable` | Get a hub variable value |
| `set_variable` | Set a hub variable value |

## Available Resources

| Resource | Description |
|----------|-------------|
| `hubitat://devices` | All devices with current state |
| `hubitat://status` | Hub mode and HSM status |
| `hubitat://home-context` | Human-readable summary of your home (devices grouped by type) |

## CLI Commands

```bash
hubitat-mcp setup    # Interactive setup
hubitat-mcp start    # Start server (default)
hubitat-mcp status   # Check connectivity
hubitat-mcp update   # Pull latest + rebuild
hubitat-mcp help     # Show help
```

## Deployment

### Raspberry Pi (alongside Homebridge)

```bash
# Clone and set up
cd /opt
git clone https://github.com/rfhayn/hubitat-mcp-server.git
cd hubitat-mcp-server
./setup.sh   # select "yes" for systemd service
```

The setup script installs a systemd service that auto-starts on boot and restarts on crash.

### Docker

```bash
cp .env.example .env
# Edit .env with your credentials
docker compose up -d
```

### macOS (launchd)

The setup script can install a launchd service for auto-start on login.

## Architecture

```
Claude (mobile/web/desktop)
    │ HTTPS
    ▼
ngrok (embedded in server)
    │ localhost
    ▼
MCP Server (Node.js)
    │ HTTP REST
    ▼
Hubitat Hub (Maker API)
    │
    ▼
Your Devices
```

## Device Aliasing

After setup, a `devices.json` file is generated with aliases for each device:

```json
{
  "aliases": {
    "12": ["kitchen light"],
    "15": ["living room lamp", "living room light"],
    "22": ["front door lock", "front door"]
  }
}
```

Edit this file to add custom aliases. Claude can then use natural names like "turn on the kitchen light."

## Health Check

```bash
curl http://localhost:3000/health
```

Returns hub connectivity, tunnel status, and uptime.

## License

MIT