ha-analytics-mcp

Historical data analytics for Home Assistant: statistics, trends and session detection computed server-side, sized for small local models.

This is a read-only MCP server that answers questions about your own home's recorded sensor history: how much energy the car charger used last month, which room is coldest at 6am, how many times the washing machine ran last week. No tool in it can turn anything on, change a setting or write to Home Assistant. It is unrelated to analytics.home-assistant.io, Home Assistant's opt-in installation-statistics service; this server only reads your own instance's recorder database.

What it looks like in use

"How many times did I charge the car in February, and is that more than usual?"

The server resolves "February" to the last complete February in local time, reads hourly statistics for the charger's power sensor, groups readings above a threshold into sessions (bridging short dropouts), then runs the same detection over the reference period. One tool call returns the session count, total duration, the session list and the delta versus last year.

"Which rooms were coldest last week, and by how much?"

One call with four temperature entity_ids and aggregations: ["mean","min","max"] returns a single four-row comparison table. The model does not fetch four series and compare them; it reads a table that is already sorted, aligned and unit-checked.

"Did we use more electricity this month than last month?"

The server reads the meter's cumulative statistic, computes end minus start for both periods, resolves the reference dates itself and returns both totals plus the absolute and percentage delta. The model never sees a meter reading and never subtracts dates.

Related MCP server: Semantic BI MCP

Why this server exists

Home Assistant's built-in MCP integration exposes live entity states and service calls, but no recorder history and no long-term statistics. The established community servers are built around device control and configuration, and the ones that do expose history return raw records for the model to interpret. Handing a model a JSON array of 8,760 hourly readings and asking for the average costs tens of thousands of tokens, and the arithmetic still comes back wrong often enough to be useless.

This server keeps the data out of the model entirely. It resolves the period, picks the right recorder API, fetches the minimum rows, does the arithmetic itself and returns a compact table holding the answer. In our test sessions, typical responses stay in the low hundreds of tokens regardless of how much history was scanned.

Get started

You need a Home Assistant long-lived access token: open your HA profile page (/profile), scroll to Long-Lived Access Tokens, click Create Token and copy it (it is shown only once). A dedicated HA user account keeps the audit trail clean.

npx (Claude Desktop, Claude Code, any stdio MCP client)

claude mcp add ha-analytics \
  -e HA_URL=https://homeassistant.local:8123 \
  -e HA_TOKEN=<your-long-lived-token> \
  -- npx -y ha-analytics-mcp

Or as client configuration JSON:

{
  "mcpServers": {
    "ha-analytics": {
      "command": "npx",
      "args": ["-y", "ha-analytics-mcp"],
      "env": {
        "HA_URL": "https://homeassistant.local:8123",
        "HA_TOKEN": "<your-long-lived-token>"
      }
    }
  }
}

Requires Node.js 22 or newer. With no arguments the server speaks stdio, which is what MCP clients launch.

Docker

{
  "mcpServers": {
    "ha-analytics": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "HA_URL", "-e", "HA_TOKEN",
        "ghcr.io/ffleurey/ha-analytics-mcp"
      ],
      "env": {
        "HA_URL": "https://homeassistant.local:8123",
        "HA_TOKEN": "<your-long-lived-token>"
      }
    }
  }
}

-i is required: the container talks MCP over stdin/stdout.

HTTP mode (LAN, or several clients against one instance)

docker run --rm -p 3000:3000 \
  -e HA_URL=https://homeassistant.local:8123 \
  -e HA_TOKEN=<your-long-lived-token> \
  -e HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN=$(openssl rand -hex 32) \
  ghcr.io/ffleurey/ha-analytics-mcp --http

The MCP endpoint is POST /mcp (Streamable HTTP); /health reports liveness without revealing your instance. The security contract is enforced at startup, not documented as advice:

• The default bind address is 127.0.0.1, reachable only from the machine running the server.

• Binding anywhere else (HOST=0.0.0.0, a LAN address) requires MCP_HTTP_TOKEN. The server refuses to start otherwise, with a message explaining why.

• When MCP_HTTP_TOKEN is set, every /mcp request must carry Authorization: Bearer <token>, or the token as a ?token=<token> query parameter for clients that cannot set a custom header (such as Home Assistant's built-in MCP integration, see below). Comparison is constant-time either way.

One server process talks to exactly one Home Assistant instance. For two homes, register two MCP servers with different names: the client routes by name, and no tool needs a "which home" argument.

A Home Assistant add-on with zero-token setup (the Supervisor provides credentials, so there is no long-lived token to create or paste) is the next planned packaging step.

Use with Home Assistant Assist

Home Assistant's built-in stack, the Model Context Protocol integration plus a conversation agent, can talk to this server directly, without any extra chat UI. This path needs nothing beyond HA itself and a local or remote LLM connection. It works, with a few rough edges listed at the end of this section.

1. Deploy the server in HTTP mode (see above) somewhere reachable from your Home Assistant instance, with MCP_HTTP_TOKEN set.

2. Settings → Devices & services → Add Integration → "Model Context Protocol", and enter the server URL with the token as a query parameter, e.g. http://<server-host>:3000/mcp?token=<your-MCP_HTTP_TOKEN>. HA's MCP client has no token field, so the query parameter is the only way to authenticate. Requires Home Assistant 2026.2 or later for Streamable HTTP support; older versions only speak the deprecated SSE transport, which this server does not implement. Home Assistant logs full request URLs (including the token) at INFO level, so use a dedicated, low-privilege token for this integration rather than reusing one from another client.

3. Add a conversation agent that supports tool calling. With the Ollama integration, raise num_ctx to at least 16k: this server's tool definitions alone are about 4.2k tokens, and Ollama's default num_ctx (8192) leaves too little room for the conversation once they are loaded. The llama.cpp integration pointed at an OpenAI-compatible endpoint (LM Studio, for example http://<lan-ip>:1234/v1) works as well.

4. In the agent's options, enable this server's MCP API. Enable Assist's own API too if you want device control from the same agent; tool names get a namespace prefix when both are selected.

5. Paste the agent instructions below into the agent's prompt field. Home Assistant's MCP client discards this server's own instructions (it never reads them), so without this step the model gets no guidance on entity discovery, tool choice or time formats.

6. Settings → Voice assistants → Add assistant, and create a pipeline using that conversation agent.

7. Chat in Assist.

Agent instructions, to paste verbatim into the conversation agent's prompt field:

You are a data analyst for this Home Assistant instance's history and statistics.
Answer from tool results only. State the sensor, period, and aggregation. Keep answers short and factual.
Never guess entity_ids — resolve them first with ha_history_list_entities, preferring areas/device/device_classes filters over free-text search.
For multi-area climate comparisons, one call with areas=[...] and device_classes=["temperature","humidity"] usually finds what you need.
For people or phone location history, use ha_history_list_entities with domains=["person"], domains=["device_tracker"], or both in one call.
Use ha_history_list_devices only when the device or area is still unclear, ha_history_list_device_entities only for one-device inspection, and ha_history_list_areas only when the exact area name is unknown.
If discovery returns weak or ambiguous matches, retry with a tighter filter before asking the user.
If a discovery call returns no matches, read the inventory included in its response: when the thing you look for is not listed there, it does not exist — report that to the user instead of retrying other search words.
Tool choice: ha_history_get_sensor_stats for instantaneous measurements, ha_history_get_consumption for cumulative meters, ha_history_detect_sessions for threshold-based activity, ha_history_get_state_history for discrete-state timelines, ha_history_get_state for current state.
Time formats: relative ("7d", "30d", "24h"), named ("last month", "yesterday", "Q1"), or ISO date. Default period: last 30 days.
If GetLiveContext and device-control (Hass*) tools are also available: prefer GetLiveContext for current values of exposed entities, use the ha_history_* tools for history, statistics, and entities GetLiveContext cannot see, and pass plain names and areas (never entity_ids) to the control tools.
Tool results may contain fenced (triple-backtick) code blocks holding compact tables — keep them fenced verbatim in your answer instead of reflowing them into prose.

Known limitations of this path, all on Home Assistant's side rather than this server's: tool calls have a 10-second timeout, hardcoded by HA's MCP client (very wide analytics queries can hit it; narrow the period if that happens). Assist's chat history expires after 5 minutes of inactivity. The agent instructions must be pasted manually every time you create or edit the agent, because Home Assistant has no mechanism to fetch them from the server.

Tools

Ten tools, all read-only. The discovery tools narrow a room or appliance concept down to exact entity_ids; the analytics tools then take those ids and return computed answers.

Every time parameter accepts what the user actually said: "7d", "last month", "february", "last winter", "Q1" or an ISO date. The server resolves it in the instance's timezone and echoes the resolved bounds back. Full parameter reference: TOOLS.md.

Designed for small models

The constraint this server is built against is an 8B model with an 8k context window, not a frontier model with a million. That constraint shapes the design rather than the tuning. Tool payloads are compact plain-text tables with a header stating sensor, period, aggregation and unit: cheaper to tokenize than nested JSON, and in our test sessions small models read values back out of them more accurately. All arithmetic happens in the server (date math, unit handling, deltas, percentages, session boundaries), because every reasoning step removed from the model is a step that cannot go wrong.

Errors teach recovery instead of reporting failure. Each error is a sentence saying what happened, why and what to do next, so the model corrects itself instead of hallucinating a plausible number. Empty discovery results include the complete inventory of what does exist plus an explicit stop rule, so asking about equipment your home does not have gets "that isn't monitored" within two or three tool calls instead of minutes of synonym-guessing before the same answer.

The design follows the MCP-server recommendations in mcpscope-chat-template (docs/MCP-DESIGN.md), and the server is developed and evaluated against local models with mcpscope, a workbench for benchmarking MCP servers against local (LM Studio, Ollama) or remote models with per-tool reliability and token-cost scoring. DESIGN.md records the design decisions in detail.

How it compares

Home Assistant's built-in mcp_server integration gives a model live state and service calls, with no access to the recorder's history or long-term statistics. The large community servers, led by homeassistant-ai/ha-mcp, are broad control-and-configuration surfaces, and the ones that expose history return raw records for the model to interpret. This server goes the other way: a small, read-only, single-purpose surface where every tool returns a computed answer rather than the data behind it, and nothing can change the state of your home.

It is meant to sit alongside a control server, not to replace one. If what you need is device control, automation management or a general-purpose assistant, one of the servers above will serve you better; COMPARISON.md maps the whole landscape, with links, so you can pick what fits.

Configuration

See .env.example for the same list in file form.

Security

The server is read-only: it exposes no tool that calls a Home Assistant service, writes state or modifies configuration. The HA token is still a full-access token, so treat it accordingly: use a dedicated account and keep it in the environment, never in a committed file. TLS is verified by default; HA_INSECURE_TLS=1 exists for local instances with a private CA and should be a last resort, since the token travels in every request header. HTTP mode defaults to loopback and refuses to bind elsewhere without a bearer token, and the /health endpoint returns only status and uptime. Historical statistics are cached in memory only and cleared when the process exits.

Documentation

• TOOLS.md: full tool surface: parameters, period formats, discovery flows, example outputs

• DESIGN.md: design rationale: server-side computation, caching, error handling, API strategy

• COMPARISON.md: how this server relates to the other Home Assistant MCP servers

• CACHE.md: current cache behavior, its limits near "now" and the planned redesign

• CONTRIBUTING.md: development workflow: lint, tests, smoke-testing

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first; it describes the change workflow the project expects. If you are proposing a new tool, say which question a small model should be able to answer with it in one call.

License

Apache License 2.0. See LICENSE and NOTICE.