Tool reference

hive-mcp has 24 tools in 5 toolsets: 13 read and 11 write. It also has 5 prompts.

Each tool is labelled with the setting it needs:

Label	Registered when
🟢 read	Always
🟠 write	HIVE_ALLOW_WRITES=true

Every tool also needs its toolset to be enabled in HIVE_TOOLSETS, which enables all toolsets by default. Temperatures are in °C, and heating targets go from 5 to 32 in steps of 0.5. Times are in the home’s local time. Read tools return compact summaries, and many take raw: true for Hive’s full objects and fresh: true to skip the short cache.

Contents

• home: Login, a one-call overview of the home, the list of Hive devices with batteries and signal, and holiday mode.
• heating: Heating zones and radiator valve (TRV) zones: temperatures, modes and schedules; set the temperature or mode, boost and cancel a boost.
• hotwater: Hot water: status and schedule; switch it on, off or back to its schedule, boost and cancel a boost.
• devices: Smart plugs, lights and sensors: on or off, power use, brightness, colour temperature, open or closed.
• raw: A raw API escape hatch for anything the other tools don’t cover. It is limited to GET requests unless writes are enabled.

home

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

Tool	Access	Summary
hive_auth_complete	🟢 read	Finish Hive login
hive_auth_start	🟢 read	Start Hive login
hive_auth_status	🟢 read	Hive login status
hive_cancel_holiday_mode	🟠 write	Cancel holiday mode
hive_get_holiday_mode	🟢 read	Get holiday mode
hive_get_overview	🟢 read	Home overview
hive_list_devices	🟢 read	List Hive devices
hive_set_holiday_mode	🟠 write	Set holiday mode

hive_auth_complete

🟢 read

Finish a login started with hive_auth_start by giving the code Hive texted to the account’s phone. This also registers the server as a remembered device, so it won’t need a code again.

Argument	Type	Required	Description
code	string	yes	The code from the text message Hive sent to the account’s phone

hive_auth_start

🟢 read

Start logging this server in to Hive with HIVE_USERNAME and HIVE_PASSWORD. If this server is already a remembered device, that’s the whole login. Otherwise Hive texts a code to the account’s phone: ask the user for it and pass it to hive_auth_complete within about three minutes. Only use this when the user asks to log in or a tool says the server isn’t logged in; it sends a real text message.

No arguments.

hive_auth_status

🟢 read

Show whether this server is logged in to Hive: the account, whether this server is a remembered device (so it can log in again without an SMS code), when the current token expires and any login error. Never shows passwords, tokens or device secrets.

No arguments.

hive_cancel_holiday_mode

🟠 write

Cancel holiday mode, so the heating and hot water go back to their normal settings straight away.

No arguments.

hive_get_holiday_mode

🟢 read

Show whether holiday mode is set: when it starts and ends and the temperature the heating holds while you’re away.

No arguments.

hive_get_overview

🟢 read

A one-call snapshot of the home: every heating zone and TRV zone (current and target temperature, mode, boost, whether it’s calling for heat), the hot water, plugs, lights and sensors, holiday mode, and anything that needs attention: low batteries, offline devices and discontinued hardware. A good first call.

Argument	Type	Required	Description
fresh	boolean		Ask Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)

hive_list_devices

🟢 read

List the Hive hardware: hub, thermostats, boiler module, radiator valves (TRVs), plugs, bulbs and sensors, with online status, battery level, signal strength, model and firmware. Filter by type, low battery or offline.

Argument	Type	Required	Description
fresh	boolean		Ask Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)
low_battery	boolean		Only battery devices at or below 25%
offline	boolean		Only devices Hive says are offline
raw	boolean		Return Hive’s full objects instead of compact summaries (much larger)
type	string		Only devices of this type, for example trv, thermostatui, boilermodule, hub, activeplug, warmwhitelight, contactsensor

hive_set_holiday_mode

🟠 write

Set holiday mode: from start (default now) until end, the heating holds one temperature, then the normal settings resume. Replaces any holiday mode already set. Confirm the dates and temperature with the user first.

Argument	Type	Required	Description
end	string	yes	When it ends and the normal schedule resumes, as YYYY-MM-DD or YYYY-MM-DDTHH:MM in the home’s local time
temperature	number (5–32)	yes	Temperature to keep the home at while away, in °C (5 to 32 in steps of 0.5; frost protection is usually 7)
start	string		When holiday mode starts, as YYYY-MM-DD or YYYY-MM-DDTHH:MM in the home’s local time (default now)

heating

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

Tool	Access	Summary
hive_boost_heating	🟠 write	Boost heating
hive_cancel_heating_boost	🟠 write	Cancel heating boost
hive_get_heating	🟢 read	Get heating
hive_get_heating_schedule	🟢 read	Get heating schedule
hive_list_trvs	🟢 read	List radiator valves
hive_set_heating_mode	🟠 write	Set heating mode
hive_set_heating_temperature	🟠 write	Set heating temperature

hive_boost_heating

🟠 write

Boost a zone: heat to a temperature for a number of minutes, then go back to the previous mode. Replaces any boost already running.

Argument	Type	Required	Description
temperature	number (5–32)	yes	Temperature to boost to, in °C (5 to 32 in steps of 0.5)
minutes	integer (1–360)		How long to boost for, in minutes (default 60, at most 360)
zone	string		Heating zone or TRV zone, by name (for example “Heating” or “Bedroom”) or ID. Can be left out when there’s only one. See hive_get_heating

hive_cancel_heating_boost

🟠 write

Stop a zone’s boost early and go back to the mode (and, for manual or off, the temperature) it had before.

Argument	Type	Required	Description
zone	string		Heating zone or TRV zone, by name (for example “Heating” or “Bedroom”) or ID. Can be left out when there’s only one. See hive_get_heating

hive_get_heating

🟢 read

Show the heating: for each heating zone (a Hive thermostat) and TRV zone (Hive radiator valves), the current temperature, target temperature, mode (schedule, manual, off or boost), boost time left, whether it’s calling for heat, what the schedule asks for now and next, and thermostat or valve batteries.

Argument	Type	Required	Description
fresh	boolean		Ask Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)
raw	boolean		Return Hive’s full objects instead of compact summaries (much larger)
zone	string		Only this zone, by name or ID (default every heating zone and TRV zone)

hive_get_heating_schedule

🟢 read

Show a zone’s weekly heating schedule: for each day, the periods and the target temperature for each, in the home’s local time. Also says what the schedule asks for now and when it next changes.

Argument	Type	Required	Description
zone	string		Heating zone or TRV zone, by name (for example “Heating” or “Bedroom”) or ID. Can be left out when there’s only one. See hive_get_heating

hive_list_trvs

🟢 read

List the Hive radiator valves (TRVs) by zone: each zone’s temperature, target and mode, and each valve’s battery, signal, online status, calibration, mounting and child lock.

Argument	Type	Required	Description
fresh	boolean		Ask Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)

hive_set_heating_mode

🟠 write

Switch a zone between schedule (follow the weekly schedule), manual (hold one temperature) and off (frost protection only). Cancels a boost.

Argument	Type	Required	Description
mode	"schedule" | "manual" | "off"	yes	schedule (follow the heating schedule), manual (hold one temperature) or off (frost protection only)
temperature	number (5–32)		With manual: the temperature to hold, in °C (5 to 32 in steps of 0.5). Default: the zone’s current target
zone	string		Heating zone or TRV zone, by name (for example “Heating” or “Bedroom”) or ID. Can be left out when there’s only one. See hive_get_heating

hive_set_heating_temperature

🟠 write

Set a zone’s target temperature. In schedule mode this lasts until the next scheduled change, like turning the thermostat dial; pass mode=manual to hold it. If the zone is off, the target is saved but nothing heats until the mode changes.

Argument	Type	Required	Description
temperature	number (5–32)	yes	Target temperature in °C, 5 to 32 in steps of 0.5
mode	"manual" | "schedule"		Also switch mode: manual (hold this temperature) or schedule (just until the next scheduled change, as turning the dial does)
zone	string		Heating zone or TRV zone, by name (for example “Heating” or “Bedroom”) or ID. Can be left out when there’s only one. See hive_get_heating

hotwater

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

Tool	Access	Summary
hive_boost_hot_water	🟠 write	Boost hot water
hive_cancel_hot_water_boost	🟠 write	Cancel hot water boost
hive_get_hot_water	🟢 read	Get hot water
hive_get_hot_water_schedule	🟢 read	Get hot water schedule
hive_set_hot_water_mode	🟠 write	Set hot water mode

hive_boost_hot_water

🟠 write

Heat the hot water now for a number of minutes, then go back to the previous mode.

Argument	Type	Required	Description
minutes	integer (1–360)		How long to heat the water for, in minutes (default 60, at most 360)

hive_cancel_hot_water_boost

🟠 write

Stop a hot water boost early and go back to the previous mode.

No arguments.

hive_get_hot_water

🟢 read

Show the hot water: whether it’s heating now, the mode (schedule, on, off or boost), boost time left, and what the schedule asks for now and next.

Argument	Type	Required	Description
fresh	boolean		Ask Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)
raw	boolean		Return Hive’s full objects instead of compact summaries (much larger)

hive_get_hot_water_schedule

🟢 read

Show the weekly hot water schedule: for each day, when the hot water is on and off, in the home’s local time.

No arguments.

hive_set_hot_water_mode

🟠 write

Switch the hot water on (it stays on until changed), off, or back to its schedule. Cancels a boost. For a limited time, use hive_boost_hot_water instead of on.

Argument	Type	Required	Description
mode	"on" | "off" | "schedule"	yes	on (stay on until changed), off, or schedule (follow the hot water schedule)

devices

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

Tool	Access	Summary
hive_list_smart_devices	🟢 read	List plugs, lights and sensors
hive_set_light	🟠 write	Control a light
hive_set_plug	🟠 write	Switch a smart plug

hive_list_smart_devices

🟢 read

List Hive smart plugs (on or off, power use), lights (on or off, brightness, colour temperature) and sensors (window and door sensors open or closed, motion sensors), with online status and batteries.

Argument	Type	Required	Description
fresh	boolean		Ask Hive again instead of using a reading from the last few seconds (HIVE_CACHE_SECONDS)
kind	"plugs" | "lights" | "sensors"		Only plugs, lights or sensors (default all)
raw	boolean		Return Hive’s full objects instead of compact summaries (much larger)

hive_set_light

🟠 write

Switch a Hive light on or off, and set its brightness or (for tuneable and colour bulbs) its white colour temperature.

Argument	Type	Required	Description
brightness	integer (5–100)		Brightness in percent, 5 to 100 (rounded to the nearest 5, as the Hive app does)
colour_temperature	integer (2700–6535)		White colour temperature in kelvin, for tuneable and colour bulbs: about 2700 (warm) to 6500 (cool)
light	string		Light, by name or ID (see hive_list_smart_devices). Can be left out when there’s only one
on	boolean		true to switch on, false to switch off. Setting a brightness or colour temperature also switches the light on

hive_set_plug

🟠 write

Switch a Hive smart plug on or off. Check what’s plugged in with the user before switching it off.

Argument	Type	Required	Description
on	boolean	yes	true to switch the plug on, false to switch it off
plug	string		Smart plug, by name or ID (see hive_list_smart_devices). Can be left out when there’s only one

raw

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

Tool	Access	Summary
hive_api_request	🟢 read	Raw Hive API request

hive_api_request

🟢 read · destructive

Call any path of Hive’s API (the undocumented “beekeeper” API the Hive app uses) directly, for anything the other tools don’t cover, such as /nodes/all, /devices, /products or /actions. All methods are allowed. Changes go straight to Hive with no checks, so confirm them with the user first.

Argument	Type	Required	Description
path	string	yes	Path relative to https://beekeeper.hivehome.com/1.0, for example /nodes/all or /holiday-mode
body	any		JSON request body for POST, PUT and DELETE
method	"GET" | "POST" | "PUT" | "DELETE"		HTTP method: GET (default), POST, PUT or DELETE
query	object		Query string parameters

Prompts

Prompts are ready-made requests that tell the model which tools to call and what to report. In Claude Code they appear as slash commands, such as /mcp__hive__home_check.

going_away

Set the home up for a trip: holiday mode with a frost-safe temperature, and a check of anything left on.

Argument	Required	Description
leave		When you leave (YYYY-MM-DD or YYYY-MM-DDTHH:MM; default now)
return	yes	When you’re back (YYYY-MM-DD or YYYY-MM-DDTHH:MM)

home_check

A quick check of the home: temperatures, what the heating and hot water are doing, holiday mode, and any low batteries or offline devices.

hot_water_now

Get hot water for a bath or shower: check whether it’s already on and boost it if not.

Argument	Required	Description
minutes		How long to heat the water for, in minutes (default 30)

schedule_review

Review the heating and hot water schedules for comfort and wasted energy, and suggest changes.

warm_up

Boost the heating to a comfortable temperature for a while, checking the current state first.

Argument	Required	Description
temperature		Temperature to boost to in °C (default 21)
minutes		How long for, in minutes (default 60)
zone		Which heating zone (default the main one)