hass-history-mcp

An MCP (Model Context Protocol) server that gives Claude access to historical Home Assistant data — something the standard Home Assistant MCP integration doesn't expose. It answers questions like:

• How much power has a given entity drawn over the last week?

• What's my estimated energy consumption (kWh) for a device or circuit?

• Has a device been offline recently, and for how long?

• What was the last reported state/value of an entity, and how long ago?

It works by querying an existing InfluxDB 1.8 instance that Home Assistant is already writing sensor data to (via the built-in InfluxDB integration), rather than talking to Home Assistant's recorder database directly. This means it can see further back than HA's default recorder purge window (commonly 10 days), since InfluxDB retention is independent of that.

How it works

Home Assistant's InfluxDB integration writes each entity's state as a point tagged with entity_id and domain, with the numeric value in a value field. The measurement name is usually the entity's unit of measurement (e.g. W, kWh, %), which varies per sensor — so every query in this server matches across measurements with a regex (/.*/) and filters by the entity_id tag instead. This makes the tools work regardless of your exact default_measurement configuration.

Two things to know about real-world databases:

• friendly_name is usually a field, not a tag (often friendly_name_str). Only entity_id and domain are reliably tags, so you can't GROUP BY friendly name unless you've added it to tags_attributes in your Home Assistant InfluxDB config. Adding it applies to new data only.

• The same entity can appear in several measurements. Integrations that set a different default_measurement write to names like sensor.my_entity_battery alongside the unit-based %. Because InfluxQL applies LIMIT per series, a query spanning measurements returns one row per measurement — so "most recent" must be resolved by comparing timestamps, not by taking the first row. get_last_seen and get_device_uptime handle this; keep it in mind for your own run_influxql queries.

Related MCP server: InfluxDB MCP Server

Timezones

InfluxDB stores everything in UTC. Set LOCAL_TZ to your IANA zone (default America/Toronto) so that bucketed queries align to local midnight rather than UTC midnight — otherwise a "daily" energy total silently covers a window offset by your UTC offset. Every history tool also accepts a per-call tz argument that overrides LOCAL_TZ, and returns timestamps carrying a local offset. Use the zone name rather than a fixed offset so daylight-saving transitions are handled correctly.

Tools

Configuration

Set via environment variables:

The compose files read these from your environment, so nothing host-specific is committed. Set them in Portainer under Stack → Environment variables, or in a .env file beside the compose file:

INFLUXDB_HOST=10.0.0.5
LOCAL_TZ=America/Toronto

Requires the MCP Python SDK v2 (mcp>=2). v1's mcp.server.fastmcp module was removed in 2.x — MCPServer replaces FastMCP.

Running with Docker

docker compose up -d --build

docker-compose.yml runs it standalone. If you'd rather add it to an existing stack, docker-compose.snippet.yml holds just the service block — paste it under that file's services: key.

Portainer

Use Stacks → Add stack → Repository and point it at this repo, so Portainer has the source needed to build the image. The Web editor tab can't build from a Dockerfile — pasting the compose file there will fail unless you swap build: . for a prebuilt image:.

Once running, point your MCP client (e.g. Claude Desktop) at:

http://<host>:8006/mcp

Verifying your schema

Before relying on the results, confirm the InfluxDB schema matches what this server expects. Run these in order — each is bounded and cheap:

-- 1. Measurement names (these are your units: W, kWh, %, ...)
SHOW MEASUREMENTS LIMIT 20

-- 2. Confirm the entity_id tag exists
SHOW TAG VALUES FROM /.*/ WITH KEY = "entity_id" LIMIT 10

-- 3. Confirm the field is named `value`, against ONE known measurement
SELECT * FROM "W" WHERE time > now() - 1h LIMIT 1

Do not run SELECT * FROM /.*/ LIMIT 1. LIMIT applies per series, not globally, so that query materializes one row for every series across every measurement at once. On a database with a few thousand entities it can grow InfluxDB's memory to many gigabytes and trigger the kernel OOM killer — taking down InfluxDB and potentially the whole host. Always bound schema checks to a single measurement and a time range, as in step 3 above.

If your tags_attributes / default_measurement Home Assistant config is customized, the field name might not be value — in that case, adjust the queries in server.py accordingly.

License

MIT — use however you like.