# Hubitat MCP Server

A production-ready **Model Context Protocol (MCP) server** for Hubitat home automation hubs. Control and manage your Hubitat devices directly from Claude Desktop or any MCP-compatible AI assistant.

## Features

✅ **List all devices** — Get a complete inventory of your Hubitat devices with IDs, names, types, and current state  
✅ **Get device details** — Retrieve full device information including capabilities, attributes, and available commands  
✅ **Send commands** — Turn devices on/off, toggle, set brightness/levels, and execute custom commands  
✅ **Query device state** — Check attribute values (temperature, switch state, battery level, etc.)  
✅ **Search devices** — Find devices by name, type, or room  
✅ **List available commands** — See what commands each device supports  

## Requirements

- **Hubitat Elevation Hub** with [Maker API](https://docs.hubitat.com/index.php?title=Maker_API) installed
- **Python 3.10+**
- **MCP Python SDK v2.x**
- Internet connectivity (for Claude Desktop integration)

## Installation

### 1. Clone or download the server

```bash
git clone https://github.com/yourusername/hubitat-mcp-server.git
cd hubitat-mcp-server
```

### 2. Install dependencies

```bash
pip install mcp requests python-dotenv
```

### 3. Configure your Hubitat credentials

Get your Maker API details from your Hubitat hub:
1. Log into your Hubitat hub at `http://[hub-ip]:8080`
2. Go to **Apps** → **Maker API**
3. Note your **App ID** and **Access Token**

Create a `.env` file:

```bash
HUBITAT_TOKEN=your_access_token_here
HUBITAT_BASE_URL=http://[HUB_IP]/apps/api/[APP_ID]  # Replace with your hub IP and App ID
```

Or set environment variables directly:

```bash
export HUBITAT_TOKEN="your_token"
export HUBITAT_BASE_URL="http://[HUB_IP]/apps/api/[APP_ID]"
```

### 4. Test the server locally

```bash
python3 hubitat-mcp-server.py
```

The server will listen on **stdio** and wait for MCP protocol messages.

## Integration with Claude Desktop

Add the server to your Claude Desktop configuration:

**File:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hubitat": {
      "command": "python3",
      "args": ["/path/to/hubitat-mcp-server.py"],
      "env": {
        "HUBITAT_TOKEN": "your_token_here",
        "HUBITAT_BASE_URL": "http://[HUB_IP]/apps/api/[APP_ID]"
      }
    }
  }
}
```

Restart Claude Desktop. The Hubitat tools will now be available.

## Usage Examples

### List all devices

```
Claude: "List all my Hubitat devices"
```

The server returns all 64 devices (or however many you have) with:
- Device ID
- Name (label)
- Type
- Room assignment
- Current state/attributes
- Available capabilities

### Control a device

```
Claude: "Turn on the kitchen light"
```

The server finds the "Kitchen Light" device and sends the `on` command.

### Check device state

```
Claude: "What's the temperature in the living room?"
```

The server queries the temperature sensor and returns the current value.

### Search for devices

```
Claude: "Show me all motion sensors"
```

The server searches for devices matching "motion" and returns all matches.

### Set brightness

```
Claude: "Set the family room light to 50% brightness"
```

The server sends `setLevel` command with value `50` to the appropriate dimmer.

## Available Tools

The server exposes these MCP tools to Claude:

### `list_devices`
Returns all devices with basic info (id, name, type, room, capabilities, status).

### `get_device`
Get detailed information about a specific device.

**Parameters:**
- `device_id` (string): The device ID

### `send_command`
Send a command to a device.

**Parameters:**
- `device_id` (string): The device ID
- `command` (string): Command name (on, off, toggle, setLevel, etc.)
- `value` (string, optional): Command parameter (e.g., brightness level)

### `list_device_commands`
List all available commands for a device.

**Parameters:**
- `device_id` (string): The device ID

### `get_device_attribute`
Get the current value of a specific device attribute.

**Parameters:**
- `device_id` (string): The device ID
- `attribute` (string): Attribute name (switch, level, temperature, etc.)

### `search_devices`
Search for devices by name, type, or room.

**Parameters:**
- `query` (string): Search term

## Architecture

The server uses:
- **MCP Python SDK 2.x** — Model Context Protocol implementation
- **Hubitat Maker API** — Direct access to devices and commands
- **Async/await** — Non-blocking I/O for responsiveness
- **JSON serialization** — Standard protocol messages

## Limitations

- **Read-only for some attributes** — Some device states (like battery level) are read-only
- **Command validation** — The server doesn't validate commands before sending; invalid commands will error at the Hubitat end
- **Real-time updates** — Device state is fetched on-demand; there's no push notification system for state changes
- **Local network only** — Requires direct access to your Hubitat hub (same LAN or VPN)

For cloud access, you can:
1. Use Hubitat's cloud API instead of local
2. Set up a reverse proxy (Caddy, nginx, etc.) with HTTPS
3. Use a VPN to access your home network remotely

## Troubleshooting

### "Device not found" error
- Check the device ID is correct
- Run `list_devices` to see all available IDs

### "Failed to fetch devices from Hubitat"
- Verify your `HUBITAT_TOKEN` and `HUBITAT_BASE_URL`
- Check that the Maker API app is enabled on your hub
- Ensure your device running the server can reach the hub IP

### Commands don't work
- Check the command name is correct for that device type
- Run `list_device_commands device_id` to see available commands
- Some devices may require parameters (e.g., `setLevel` needs a brightness value)

### Server won't start
- Ensure Python 3.10+ is installed: `python3 --version`
- Install dependencies: `pip install mcp requests`
- Check for syntax errors: `python3 -m py_compile hubitat-mcp-server.py`

## Development

### Running in debug mode

```bash
HUBITAT_TOKEN=token HUBITAT_BASE_URL=url python3 -u hubitat-mcp-server.py
```

### Testing individual tools

You can test the server's Python functions directly:

```python
from hubitat_mcp_server import list_devices, get_device, send_command

# List devices
devices = list_devices()

# Get a specific device
device = get_device("140")

# Send a command
result = send_command("140", "on")
```

## Contributing

Contributions are welcome! Potential improvements:
- Support for device/driver configuration
- Real-time WebSocket updates
- Batch command execution
- Device grouping/scenes
- Temperature/humidity/motion sensor subscriptions
- Custom driver support

## License

MIT License — Feel free to use, modify, and distribute.

## Support

For issues, feature requests, or questions:
1. Check the Hubitat Maker API documentation
2. Verify your token and hub URL
3. Run `list_devices` to confirm connectivity
4. Open an issue with device ID and command you're trying to run

## Changelog

**v1.0.0** (2026-09-05)
- Initial release
- List, get, and control devices
- Search and attribute queries
- Full MCP protocol support

---

**Enjoy automating your Hubitat home with Claude!**