Gives an AI assistant read-only expert analysis tools for the heat pumps in a Home Assistant installation: describing configured heat pumps and available analyses, discovering the right sensors for each role, and analysing compressor cycles/short cycling, the actual heating curve versus what the heat source delivers, and room temperatures and valve behaviour. Results are computed, graded findings with data coverage and assumptions attached, plus dashboard sensors.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Heat Pump Insights Is my heat pump short cycling? Analyze the last 7 days."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your AI assistant understands why your heat pump behaves the way it does – and how to set it up better.
Heat Pump Insights is an open-source Home Assistant integration that gives AI assistants (Claude, ChatGPT, local models via Ollama – anything that talks to Home Assistant) a set of expert analysis tools for heat pumps. It works with any brand: all it needs is the heat pump's electrical power. Every additional sensor unlocks more analyses.
"Analyse my heat pump over the last seven days. Is it running efficiently, and should I change the heating curve?"
Instead of handing raw sensor history to a language model and hoping it does the maths, the integration computes the domain-specific figures – compressor cycles, short cycling, heating curve, energy signature – and hands the assistant structured, verifiable results with data coverage and assumptions attached. The model explains; the code calculates.
Home Assistant = data (your sensors and their history)
MCP / LLM API = interface (built into Home Assistant)
This project = expertise (heat pump knowledge as tested code)
LLM = interpretation (dialogue in your language)
|
|
Where | What you get |
Dashboard in Home Assistant | Key figures as sensors (starts today, runtime, short cycles, rating, actual heating-curve slope, overheated rooms, valve open share per room) and a ready-made dashboard generated from your roles, with a compressor view for high pressure and hot gas if you assign them |
AI assistant (Claude, ChatGPT, local models via MCP / Assist) | The why: graded findings with the evidence they rest on, explained in your language |
Streamlit playground | Try the analysis without installing, with examples or a history export |
Related MCP server: whoop-ai-mcp
Early development (v0.4). Cycle, heating curve and room analyses are implemented and tested; cycle detection has been checked against a vendor compressor status on a real installation. Findings are graded info / check / act: act only with clear data and only for reversible settings – the tools never recommend physical work.
Tool | Needs | Answers |
| – | Which heat pumps and sensors are configured, which analyses are available, what is missing |
| – | Finds the right sensors for each role on any heat pump and gives the reasons; the user confirms |
| power (+ outdoor temp) | How often does the compressor start? Is it short cycling? When – on mild days? |
| circuit flow (or controller target) + outdoor temp | What is my real heating curve (K/K, flow at 0 / −10 °C)? Does the heat source deliver it? |
| room thermostats (+ valves) | Which rooms are too warm or too cold? How often are their valves open? Which room limits the curve? |
| energy + outdoor temp | Did my change actually save energy, weather-corrected? |
| heat meter | Real COP and seasonal performance factor |
All tools are read-only. Nothing is ever controlled.
There is no list of supported models. Home Assistant describes every sensor the same way
(type, unit, name, device), so Heat Pump Insights recognises the roles itself – in English,
German, French, Dutch, Scandinavian and Italian wording, for ISG, ViCare, Daikin, Aquarea/HeishaMon,
Luxtronik, ESPHome sensors and anything else. The setup form is pre-filled where one sensor
clearly fits; where two fit equally well, you (or Claude, asking you) choose. Unknown wording? Add
the word to analysis/discovery.py – one line helps every user of that integration.
After setting up the integration, create a new dashboard (Settings → Dashboards → Add dashboard → New dashboard from scratch), open the raw configuration editor and enter:
strategy:
type: custom:heatpump-insights
# heat_pump: Heat pump # only needed with several heat pumpsThe dashboard builds itself from the integration's sensors and your role mapping: overview with key figures and findings, heating curve, rooms with valves. Thermostat and setting tiles are display-only.
Vendor-independent – roles instead of brand-specific entities.
Computed, not guessed – every number comes from tested code, with coverage and assumptions.
Honest about limits – missing sensors and data gaps are reported, never papered over.
Local and private – runs inside Home Assistant; the user decides what the assistant sees.
Explainable knowledge – every threshold is documented in the knowledge base with its reasoning.
streamlit run streamlit_app.py opens an interactive playground: load the bundled examples or a
Home Assistant history export (History → ⋮ → Download data) and see the cycle analysis with
interactive charts – for heat pumps and burners (gas, oil, pellets) alike.
Requires Home Assistant 2026.10 or newer.
HACS → ⋮ → Custom repositories → add https://github.com/sommer-nt/heatpump-insights (type Integration).
Install Heat Pump Insights, restart Home Assistant.
Settings → Devices & services → Add integration → Heat Pump Insights, assign your sensors.
Expose the tools to your assistant:
Claude / other MCP clients: Model Context Protocol Server integration → select the LLM API Heat Pump Insights (alongside Assist if you like).
Assist with a conversation agent (OpenAI, Anthropic, Ollama, …): in the agent's options, enable Heat Pump Insights as an LLM API.
Vision and aim – what we build, for whom, and what we deliberately do not build
Use cases – concrete questions the assistant must answer well
Architecture – layers, data flow, roles, tool contract
Validation plan – how we prove the analyses are right
Knowledge base – the heat pump expertise behind the tools
Contributing – device profiles, data, code, translations
Apache-2.0
This server cannot be deployed
Home energy for AI assistants: live Power flow, Energy history, solar forecast, and device control.
Solar, weatherization, EV charging, battery and heat-pump decision tools for AI agents.
Heating, ventilation and energy engineering calculations and diagnostics for AI agents.
Read-only electricity, gas, and weather data with structured provenance and units.