hive-mcp

Open source · MIT · Unofficial · Model Context Protocol

Talk to your Hive heating.

hive-mcp connects Claude and other AI assistants to Hive, British Gas's smart heating. Ask how warm the house is in plain English, and let the assistant boost the heating, put the hot water on or set holiday mode when you allow it.

Get started Star on GitHub
docker pull ghcr.io/mattoddie/hive-mcp
Claude · hive
It's freezing in here. Can you warm the house up? I'd like a bath later too.
hive_get_overviewfreshhive_get_hot_water
The living room is 17.5 °C: the heating is on its schedule, which holds 16 °C until 17:00. The hot water is off until 18:00.

Shall I boost the heating to 21 °C for an hour, and the hot water for 30 minutes?
Yes please.
hive_boost_heating21 °C · 60 minhive_boost_hot_water30 min
Done. The heating is boosting to 21 °C until 15:40, then goes back to its schedule, and the water will be hot in about half an hour. 🔥 One more thing: the bedroom radiator valve's battery is down to 20%.
24tools
5toolsets
5guided prompts
1SMS code, ever

Ask anything

Your home, in plain English.

The assistant picks the right tools, reads your Hive system and explains what it found. No digging through the app to see why the bedroom's cold.

“How warm is each room right now?”

get_overviewget_heating

“Boost the heating to 21 for an hour.”

get_heatingboost_heating

“Put the hot water on, I want a bath.”

get_hot_waterboost_hot_water

“We're away until the 28th. Set holiday mode.”

get_overviewset_holiday_modeset_plug

“Which Hive devices need new batteries?”

list_deviceslist_trvs

“Is my heating schedule wasting energy?”

get_heating_scheduleget_hot_water_schedule

Full coverage

24 tools for heating, hot water and more.

Grouped into 5 toolsets you can switch on and off, so the assistant only sees what you need: 13 read and 11 write tools.

home8

Login, a one-call overview of the home, the list of Hive devices with batteries and signal, and holiday mode.

heating7

Heating zones and radiator valve (TRV) zones: temperatures, modes and schedules; set the temperature or mode, boost and cancel a boost.

hotwater5

Hot water: status and schedule; switch it on, off or back to its schedule, boost and cancel a boost.

devices3

Smart plugs, lights and sensors: on or off, power use, brightness, colour temperature, open or closed.

raw1

A raw API escape hatch for anything the other tools don't cover. It is limited to GET requests unless writes are enabled.

read write ·Full tool reference →

Safe by default

It can look. It only touches the thermostat when you say so.

Tools that aren't allowed aren't registered at all. The assistant can't see them, so it can't call them or be talked into calling them.

  • Read-only out of the box. Changing anything needs HIVE_ALLOW_WRITES=true.
  • Every change is checked: 5–32 °C in steps of 0.5, boosts up to six hours.
  • No surprise texts. The server never starts a login that sends an SMS code by itself.
  • Bearer-token auth, a Host allow-list and a read-only, non-root container.
Read the security model →
read

13 tools, always on

get_overview · get_heating · get_hot_water · list_devices …
write

11 tools with HIVE_ALLOW_WRITES=true

boost_heating · set_heating_temperature · boost_hot_water · set_holiday_mode …

Built with care

The fiddly parts, handled.

Hive has no public API, and its login needs a text message. hive-mcp deals with both carefully, so you only do it once.

Docker-first

A ~20 MB distroless image for amd64 and arm64. It runs as non-root on a read-only filesystem, and only the login volume is writable.

One SMS code, once

Log in once with the code Hive texts you. The server registers itself as a remembered device, so it logs in again on its own, with no more codes.

Real Cognito SRP

It logs in the way the Hive app does, proving your password without sending it, checked against the maths of the client Home Assistant uses.

Validated changes

Targets of 5–32 °C in steps of 0.5, boosts of up to six hours, and brightness and colour within each bulb's range. Bad values never reach Hive.

Gentle on Hive

Readings are cached for 30 seconds, rate limits are retried with back-off, and a failed login is never hammered.

Tested against a mock Hive

The suite runs every tool against a fake Hive, including a Cognito that checks each SRP proof, SMS code and remembered device.

5 guided prompts turn common jobs into one step. In Claude Code they're slash commands, such as /mcp__hive__warm_up.

  • going_away
  • home_check
  • hot_water_now
  • schedule_review
  • warm_up

Works with your Hive system

Hive Active Heating and more

  • Hive thermostats
  • Multi-zone heating
  • Radiator valves (TRVs)
  • Hot water
  • Holiday mode
  • Smart plugs
  • Active lights
  • Window & door sensors

Logs in to your own Hive account and uses the same unofficial API as the Hive app and Home Assistant. A raw API tool covers anything else, limited to reads unless writes are on. Compatibility →

Works with your assistant

Streamable HTTP or stdio

  • Claude Code
  • Claude Desktop
  • VS Code
  • Cursor
  • Codex
  • Any MCP client

Run it once and share it, or start it per session with docker run -i. You can even log in from the chat with the auth tools. Client setup →

Quick start

Up and running in three steps.

  1. 1

    Have your Hive login ready

    The email and password you use in the Hive app, and the phone Hive texts your codes to. No developer account needed.

  2. 2

    Log in once and start it

    mkdir hive-mcp && cd hive-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/hive-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/hive-mcp/main/example.env -o .env
# set HIVE_USERNAME, HIVE_PASSWORD
# and MCP_AUTH_TOKEN in .env
docker compose run --rm hive-mcp login
docker compose up -d
  3. 3

    Connect your assistant

    claude mcp add --transport http hive \
  http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <token>"

    Then ask: “How warm is the house?”

Ready to talk to your heating?

Free, open source and MIT licensed. Contributions and bug reports are welcome.

Read the docs Contribute