homestack

Pulls data from personal devices into one SQLite file, then exposes it two ways: an MCP server so Claude can answer questions about it, and an HTTP API for a dashboard.

The point of the split is that neither adapter owns any logic. Both call the same functions in core/query.py, so they can't drift apart, and a UI never has to speak MCP.

Oura is the first source. Rachio, Ring, and Eight Sleep are meant to slot in as new files under core/sources/ with no schema change.

How it fits together

core/sources/*.py   pull from a vendor API, map to rows
core/store.py       SQLite: observations, events, raw, sync_state
core/query.py       the read functions — all real logic lives here
  ├── mcp_server.py   MCP adapter (7 tools)
  └── api.py          HTTP adapter (8 routes)
sync.py             one-shot pull, for cron or by hand
run.py              container entrypoint: api + mcp + a sync loop

observations is deliberately narrow — (source, metric, ts, value, unit) — so a question that spans devices, like sleep score against bedroom temperature, is one query no matter how many sources exist. raw keeps every untouched API document, so a mapping can be changed and re-derived without re-fetching.

Nothing writes to a device. The Oura scopes are read-only, and the only tool that reaches outward is sync_now, which pulls.

Setup

Register an application at https://cloud.ouraring.com/oauth/applications with redirect URI http://localhost:8765/callback — Oura rejects http for anything but the literal hostname localhost. Check every scope except Email.

python -m venv .venv && .venv/Scripts/activate    # Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                              # fill in client id + secret
python auth_oura.py                               # one-time browser consent
python sync.py --since 2020-01-01                 # full backfill

auth_oura.py writes data/tokens.json. Copy it to the server along with .env and the sync refreshes on its own from then on — the redirect URI is never used again.

Running it

Locally, for development:

uvicorn api:app --port 8770
python mcp_server.py

On Unraid, as one container plus a Tailscale sidecar:

docker compose up -d --build

Nothing is published to the LAN. The sidecar puts it on the tailnet at https://homestack.<tailnet>.ts.net, so your phone reaches it from anywhere without opening a port. On first boot the node needs one interactive login — docker logs homestack-ts prints the URL — unless you put a TS_AUTHKEY in .env.

Register the MCP server with Claude Code:

claude mcp add homestack --transport http http://192.168.88.39:8771/mcp

Two things that will bite you

Oura refresh tokens are single-use. Every refresh returns a new one and kills the old. save_tokens() writes atomically and keeps tokens.json.bak for exactly this reason. If both are lost, re-run auth_oura.py.

Heart rate needs 30-day request chunks and produces a sample roughly every five minutes, which outnumbers every other metric put together. It's off by default; set OURA_SYNC_HEARTRATE=true if you want it.

Gmail

Deliberately absent. Email is the only source an attacker can write into for free, so if it's ever added the rule is: the pull job reads it with no model in the loop, the store keeps sender, subject, and derived flags but never bodies, and there is no live mailbox tool.