Hubitat MCP Server

A TypeScript MCP server that lets Claude control your Hubitat Elevation 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 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:

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

Raspberry Pi / Linux:

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:

brew install node@22 git

Raspberry Pi / Linux:

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
2. Copy your authtoken from dashboard
3. Claim a free static domain from domains (e.g., your-name.ngrok-free.app)

Manual Setup

If you prefer not to use the setup script:

# 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:

# 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)

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:

{
  "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)

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

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)

# 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

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:

{
  "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

curl http://localhost:3000/health

Returns hub connectivity, tunnel status, and uptime.

License

MIT