Skip to main content
Glama
README.md
# Personal health MCP backend on AWS Lambda

One Lambda Function URL serves two things:
- **An MCP server for claude.ai.** It has read-only Oura Ring tools, tools to log, delete and read home health readings, a workouts tool, and one tool that feeds a report page.
- **An ingest endpoint for Apple Health data,** sent by the iPhone app Health Auto Export (HAE).

Health readings from both paths, and workouts, share one DynamoDB table.

```
claude.ai ──POST /mcp/<path-secret>──────┐      Health Auto Export (iPhone)
                                         │        │ POST /ingest/<ingest-path-secret>
                                         ▼        ▼   + header X-Ingest-Key
                  Lambda (Node 24, arm64, 512 MB, reserved concurrency 5)
                  @modelcontextprotocol/server v2, stateless Streamable HTTP
                     │                    │                          │
      SSM Parameter Store (SecureString)  │ api.ouraring.com         DynamoDB (on-demand)
      /oura-mcp/path-secret               │ (OAuth2)                 PK metric, SK ts
      /oura-mcp/ingest-path-secret        │                          weight waist body_fat lean_mass
      /oura-mcp/ingest-key                │                          bp glucose ketones protein
      /oura-mcp/oauth-client              │                          carbs fiber fat calories workout
      /oura-mcp/tokens  ◀── rotated Oura refresh token written back here
```

Operating it (redeploy, re-authorizing Oura, rotating secrets, restores, the budget alert) is covered in [docs/RUNBOOK.md](docs/RUNBOOK.md).

## Tools

Tools that take a date range accept optional `start_date` and `end_date` (`YYYY-MM-DD`, inclusive). By default they cover the last 7 days in `USER_TZ` (America/Los_Angeles). `end_date` defaults to today even when only `start_date` is given.

### Oura (read-only)

Each tool returns `{range, rows, days_without_data, notes?}`, one compact row per day. It never returns raw Oura JSON.

| Tool | Max range | Row fields |
|---|---|---|
| `get_sleep` | 92 days | `sleep_score, total_sleep_h, time_in_bed_h, deep_h, rem_h, light_h, efficiency_pct, bedtime, wake_time, resting_hr_bpm, avg_hrv_ms, avg_breath_rpm, breathing_disturbance_index, spo2_avg_pct, nap_h` |
| `get_heart_rate` | 31 days | `resting_hr_bpm, avg_hrv_ms, avg_hr_bpm, min_hr_bpm, max_hr_bpm, avg_awake_hr_bpm, avg_sleep_hr_bpm, max_workout_hr_bpm, samples` |
| `get_readiness` | 92 days | `readiness_score, temp_deviation_c, temp_trend_deviation_c, resting_hr_bpm, avg_hrv_ms` |
| `get_activity` | 92 days | `activity_score, steps, active_kcal, total_kcal, walking_equiv_km, high/medium/low_activity_min, sedentary_h, non_wear_h` |

How the Oura fields are defined:
- Sleep metrics belong to the day you woke up.
- `resting_hr_bpm` is the lowest 5-minute average during the night's main sleep, which is what the Oura app shows.
- `avg_hrv_ms` is the average HRV of that main sleep.
- Heart-rate samples arrive in UTC and are grouped into days in `USER_TZ`.

### Health readings

**`log_reading(metric, value, unit, timestamp?, context?, note?)`**
- Saves a home glucose or ketone reading you report in chat. The tool description tells the model to call it whenever you report one.
- `metric` is `glucose` or `ketones`.
- `unit` must be exactly `mg/dL` for glucose or `mmol/L` for ketones.
- Allowed ranges are glucose 20–600 mg/dL and ketones 0–10 mmol/L, inclusive. A wrong unit, an out-of-range value or a future time returns an error and **nothing is written**.
- `timestamp` defaults to now. A time without an offset, such as `2026-09-27T07:30`, is read as Los Angeles time.
- `context` is `fasting`, `post-meal` or `other`. `note` is optional, up to 200 characters.
- Saved with `source: "claude-log"`. It returns the stored row, including the exact `timestamp` that `delete_reading` needs.
- It refuses to overwrite an Apple Health reading stored at the exact same second.

**`delete_reading(metric, timestamp, value?, undo?)`**
- **Identifies a reading** by metric and time: the exact timestamp, or to the minute (e.g. `2026-10-05T07:02`, local time). If several readings share that minute, `value` picks one; otherwise the tool lists them and changes nothing.
- **Chat readings** (`claude-log`) are deleted.
- **Apple Health readings** are marked removed (`superseded_at`, `superseded_by: "chat"`) and stop counting. The reply reminds you to delete the reading in Apple Health first, because a later push that still contains it clears the mark.
- **`undo: true`** restores a removed Apple Health reading.
- **Workouts** are removed the same way: `metric` is `workout`, `timestamp` is the workout's start time (from `get_workouts`), and `value` is its duration in minutes if several started in that minute. A workout is always marked removed, never deleted, and `undo: true` restores it.

**`get_health_metrics(metric, start_date?, end_date?)`**
- `metric` is one of `weight waist body_fat lean_mass bp glucose ketones protein carbs fiber fat calories`, or `all`. `carbs` always returns **net carbs** (see *Net carbs* below). The range can be up to 92 days.
- Returns `{range, timezone, days, days_without_data, notes?}`. Each day has:
  - `protein_g`, `carbs_g` (net carbs), `total_carbs_g`, `fiber_g`, `fat_g` and `calories_kcal` as daily sums, plus `warnings` when net carbs had to be clamped or some fiber wasn't subtracted
  - `weight` (lb), `waist` (in), `body_fat` (%), `lean_mass` (lb), `bp`, `glucose` and `ketones` as lists of readings `{time, value | systolic+diastolic, unit, context?, source, note?, timestamp?}`
- `timestamp` appears on `claude-log` readings. Apple Health readings show `time` (HH:MM), which is enough for `delete_reading`.
- **Duplicates:** an Apple Health reading and a `claude-log` reading of the same metric, within 15 minutes and within 5% of each other (both systolic and diastolic for BP), count as one reading.
  - Only the `claude-log` one is returned, and a note says how many were hidden.
  - Each reading pairs with at most one other, closest in time first. Neither row is deleted.
- Responses are capped at 1,000 readings, with a note if any were left out.

### Workouts

**`get_workouts(start_date?, end_date?)`**
- Workouts recorded in Apple Health (for example Peloton rides), sent by a Health Auto Export "Workouts" automation. The range can be up to 92 days.
- Returns `{range, timezone, workouts, days, days_without_workouts, notes?}`.
  - `workouts` has one row per workout: `date`, `start` and `end` (local HH:MM), `type`, `duration_min`, `active_kcal`, `avg_hr_bpm`, `max_hr_bpm` and `source`. The energy and heart-rate fields appear only when the workout recorded them.
  - `days` has the daily totals: `workouts`, `duration_min` and `active_kcal`.
- A workout belongs to the day it started, in `USER_TZ`.
- `source` is the app that wrote the workout, from the workout's own source field, or `unknown` if the payload has none (see *Workouts* under ingest).
- **Oura duplicates:** Oura detects activities and writes them as workouts, so a ride recorded by another app can also appear as a longer Oura workout around it. An Oura workout is left out of `workouts` and the daily totals when a workout from another app overlaps it for at least half of the shorter of the two; `notes` says which one and why. It stays in the table, and Oura-only workouts such as walks are always shown.
- Workouts edited or deleted in Apple Health drop out after two pushes at least 15 minutes apart, like other samples. To remove a wrong one by hand, use `delete_reading` with `metric: "workout"`.

### Report page data

**`get_report_data(start_date?, end_date?)`**, read-only. It serves the Weekly Oura Summary report page (a claude.ai artifact that calls this connector); chats should keep using the individual tools.

| Tool | Max range | Returns |
|---|---|---|
| `get_report_data` | 366 days | `{range, timezone, health, sleep, activity, readiness, workouts}` |

- **Each section** is exactly what the matching tool returns for the same range: `health` is `get_health_metrics` with `metric: "all"`, then `get_sleep`, `get_activity`, `get_readiness` and `get_workouts`.
- **One call instead of five:** the sections run in parallel inside one invocation, and Oura's sleep periods are fetched once for both sleep and readiness.
- **A failing section** is `{error: {message}}` in its place (for example Oura's re-authorize message), and the other sections still return. The log line lists `failed_sections`.
- **366 days** lets the page load everything from its first day for a year in one call. With 10 food entries, a weigh-in, and a night of sleep, readiness and activity every day, a 366-day response is about 300 KB of JSON (about 340 KB as the HTTP response; a workout every day adds about 90 KB). Lambda's response limit is 6 MB.

### Prompts

Tools never appear in a chat's menus; Claude calls them itself. So the server also publishes a **prompt** for each tool except `get_report_data` (8 prompts), under the same name. `get_report_data` has none on purpose: it only serves the report page. Clients list these as ready-made commands:
- **claude.ai chats:** the message box's "+" menu → Connectors → this connector.
- **Claude Code:** `/mcp__<connector>__<name>`.

| Prompt | Arguments | What it does |
|---|---|---|
| `get_sleep`, `get_heart_rate`, `get_readiness`, `get_activity` | `range` | Runs the same query as the tool and attaches the data, with instructions to show it as a table |
| `get_health_metrics` | `metric`, `range` | Same, for Apple Health and chat readings |
| `get_workouts` | `range` | Same, for workouts: one row per workout, then totals |
| `log_reading` | `metric`*, `value`*, `time`, `context`, `note` | Pre-fills a request; Claude then saves the reading with the tool |
| `delete_reading` | `metric`, `timestamp` | Pre-fills a request to remove a reading or a workout, or asks you to pick one from the last 7 days |

\* required

- **`range`** takes `7d` / `30d` / `90d`, `YYYY-MM-DD`, or `YYYY-MM-DD YYYY-MM-DD`. It defaults to the last 7 days.
- **Write prompts never write.** Fetching a prompt never changes data; the actual save or delete goes through the tool.

### Net carbs

`carbs_g` always means net carbs. The switchover is set in one place, `NET_CARBS_SWITCHOVER` in [src/health.ts](src/health.ts): **2026-09-29 15:44 Pacific**. Each sample is judged by its own timestamp, not by when it arrived.

- **Before the switchover,** carbs were edited to net in Cal AI before reaching Apple Health's Carbohydrates. They count as-is, and fiber samples are ignored.
- **From the switchover on,** Carbohydrates is total carbs and net carbs = carbs − fiber.
  - Cal AI writes all of a food entry's nutrients with the same timestamp. So a fiber sample is subtracted only when a carbs sample has the same second and source app.
  - Fiber with no matching carbs isn't subtracted: it's logged and listed in the day's `warnings`. That way an entry with fiber but no carbs can't pull the total down.
- **A day never goes below 0 net carbs.** A clamp adds a warning.
- **`total_carbs_g` and `fiber_g`** count only samples from the switchover on, and are omitted for days entirely before it. So on the switchover day, `carbs_g` can be more than `total_carbs_g − fiber_g`: it also includes the net carbs entered earlier that day.

## Health data table

On-demand DynamoDB, `PK = metric`, `SK = ts`. It's named in the stack output `HealthTableName`.

- **`ts`** starts with the reading's time as ISO 8601 in UTC, to the second, e.g. `2026-09-27T14:30:00Z`.
  - UTC keeps keys sorting chronologically across DST changes and across readings sent with different offsets.
  - **Chat readings** use just that time. `delete_reading` finds them by it.
  - **Apple Health samples** add `#` and a 12-character fingerprint of the sample's source app, values and unit as sent, e.g. `2026-09-27T14:30:00Z#0ac0a6ff8250`. So:
    - a re-sent sample always lands on the same key, and ingest is safe to repeat;
    - different samples at the same second (another value, another app) get separate rows;
    - exact duplicates within one request get `~1`, `~2`, and so on.
  - The original timestamp, with its offset, is kept in `recorded_at`.
- **Each row stores:**
  - `value`, or `systolic` + `diastolic` for BP, in the normalized unit
  - `unit`
  - `original_value` (or `original_systolic` / `original_diastolic`) and `original_unit`
  - `source`: the recording app, or `claude-log`
  - `via`: `hae` or `chat`
  - optional `context` and `note`
  - `recorded_at` and `ingested_at`
- **Normalized units:**
  - weight and lean mass `lb`
  - waist `in` (cm is ÷ 2.54)
  - body fat `%` (a value of 1 or less is a fraction and is × 100)
  - bp `mmHg`
  - glucose `mg/dL` (mmol/L from Apple Health is × 18.016)
  - ketones `mmol/L`
  - protein, carbs, fiber and fat `g`
  - calories `kcal` (kJ is ÷ 4.184)
- **Retained on stack delete.** The table has `DeletionPolicy: Retain`, so readings you logged in chat survive a teardown.
- **Workouts** are rows with `metric = workout`. `ts` is the start (UTC second) plus a fingerprint of the workout's Health Auto Export `id`. Each row stores `name` (the workout type), `start`, `end`, `duration_s`, `active_kcal`, `avg_hr_bpm`, `max_hr_bpm`, `source` and `source_id` (the app that wrote it), `hae_id`, and `recorded_at` / `recorded_end` (the times as sent).
- **Bookkeeping rows.** `metric = _meta` rows record that the first Health Metrics payload and the first Workouts payload have been logged (`hae-first-payload-logged`, `hae-first-workout-payload-logged`), and when a skipped reconciliation was last logged. No tool ever reads them.
- **Permissions:** the Lambda can only `Query`, `PutItem`, `DeleteItem` and `BatchWriteItem` on this table.

## Apple Health ingest (Health Auto Export)

`POST <FunctionUrl>ingest/<ingest-path-secret>` with the header `X-Ingest-Key: <ingest-key>`. Run `npm run ingest-url` to print both.

- **Auth:** a wrong path gets a 404, and a missing or wrong key gets a 401. Both secrets are separate from the MCP secret.
- **Format:** HAE's JSON: `{"data": {"metrics": [{"name", "units", "data": [{"date", "qty" | "systolic"+"diastolic", "source", "metadata"?}]}]}}`. Dates look like `2026-09-27 07:30:00 -0700`. The shape and metric names were checked against HAE's reference server ([HealthyApps/health-auto-export-server](https://github.com/HealthyApps/health-auto-export-server)).
- **Accepted metrics:** `weight_body_mass`, `waist_circumference` (stored as `waist`), `body_fat_percentage` (`body_fat`), `lean_body_mass` (`lean_mass`), `blood_pressure`, `blood_glucose`, `protein`, `carbohydrates`, `fiber`, `total_fat` (`fat`) and `dietary_energy`.
  - Everything else (for example `saturated_fat`, which the automation also sends) is skipped and listed in `ignored_metrics`. A malformed metric entry never fails the request.
  - The log line records each metric's unit as sent (`units`).
- **Oura samples dropped:** any metric sample whose `source` contains "Oura" (in any case) is dropped. Workouts are the exception (below).
- **`source`:** set to the sample's original app, e.g. "OMRON connect".
- **Meal timing:** if HAE passes through HealthKit's glucose meal time and it says "after meal", `context` becomes `post-meal`.
- **Same-timestamp samples:** Apple Health often stamps several food entries with the same time. Each sample is stored as its own row (see `ts` above), and the daily totals add them up.
- **Re-sends:** samples already stored unchanged aren't written again. The reply counts them as `rows_unchanged`.
- **Deleted or edited samples:** on full "Previous 7 Days" and "Today" pushes, a stored sample that disappears is marked `missing_since`, then `superseded_at` if a push 15 or more minutes later still lacks it. "Today" pushes cover today's rows, so same-day edits are retired the same day. `get_health_metrics` ignores superseded rows, and nothing is ever deleted. The guard rules are in [docs/RUNBOOK.md](docs/RUNBOOK.md#health-auto-export-settings).
- **Workouts:** a "Workouts" automation sends `{"data": {"workouts": [...]}}` instead of metrics, to the same URL.
  - Read from each workout: `id`, `name`, `start`, `end`, `duration` (seconds), `activeEnergyBurned` (kcal or kJ), and `avgHeartRate` / `maxHeartRate`. If those two are missing, the `heartRate` min/avg/max object is used, then the `heartRateData` series. Export Version 1 (no `id` or `duration`, `activeEnergy` as one object) is read too.
  - The field names follow HAE's [Export Version 2 documentation](https://help.healthyapps.dev/en/health-auto-export/export-format/workouts/) and its reference server.
  - **Source:** the workout's own `source`, which real pushes send as `{"name": "Oura", "identifier": "com.ouraring.oura"}` (a plain name is read too). The name is stored as `source` and the identifier as `source_id`; without one, `source` is `unknown`. It is never guessed from the samples inside the workout, because those come from whatever was recording at the time.
  - **Workouts written by Oura are kept,** unlike Oura's metric samples: a walk Oura detected may be the only record of it. When another app recorded the same session, `get_workouts` leaves the Oura one out (see *Workouts* under Tools).
  - Re-sends land on the same row (keyed by the workout's `id`), so a workout whose numbers change is updated in place.
  - Reconciliation follows the same rules as other samples, with one difference described in the runbook.
  - The reply adds a `workouts` object with its own counts.
- **Size limit:** 6 MB (6,291,456 bytes), the most AWS allows; in practice about 5.5 MB of Health Auto Export JSON. A gzip body may inflate to the same 6 MB. Details, and what to do about a push that is too large, are in [docs/RUNBOOK.md → Payload size](docs/RUNBOOK.md#payload-size).
- **Response:** HTTP 200 with the counts, e.g. `{"accepted":4,"skipped":1,"skipped_reasons":{"oura_source":1},"rows_written":1,"rows_unchanged":3}`. `ignored_metrics` lists any unsupported metric names that were sent. The log line also records how many samples each metric carried and the automation's period.
- **First payload:** the first Health Metrics payload and the first Workouts payload are each logged once, redacted (every number becomes `"<number>"`; only 2 samples per metric or workout series and 3 workouts are kept). Find them in CloudWatch with `sam logs --stack-name oura-mcp --filter 'hae first payload'` and `--filter 'hae first workout payload'`. To log another one, delete the bookkeeping row: `aws dynamodb delete-item --table-name <HealthTableName> --key '{"metric":{"S":"_meta"},"ts":{"S":"hae-first-payload-logged"}}'`.

### Health Auto Export settings

The full settings, and what happens to samples deleted in Apple Health, are in [docs/RUNBOOK.md → Health Auto Export settings](docs/RUNBOOK.md#health-auto-export-settings). In short: REST API automations sending JSON Version 2, with Summarize Data OFF and Batch Requests OFF:
- one re-sends the **Previous 7 Days** every 5 minutes. That's the 7 days *before* today; it never includes today.
- a second sends **Today** every 5 minutes, so today's entries arrive the same day, and entries edited or deleted today are reconciled the same day.
- two more do the same for **Workouts** (Data Type "Workouts" instead of "Health Metrics").

## Setup

1. **Log in to AWS.** Use `aws login`, `aws configure sso`, or `aws configure`.
2. **Deploy.** Run `npm install`, then `npm run deploy`.
   - First copy `deploy.env.example` to `deploy.env` and fill it in: region, budget email and amount, timezone and reserved concurrency. `deploy.env` is git-ignored.
   - The deploy creates any missing secrets (`path-secret`, `ingest-path-secret`, `ingest-key`), builds with esbuild and deploys the stack.
   - It doesn't print the connector or ingest URLs, because they contain secrets. Run `npm run url` and `npm run ingest-url` to see them.
3. **Register an Oura app.** Create it at <https://cloud.ouraring.com/oauth/applications> (or on the newer developer portal) with redirect URI `http://localhost:8787/callback`.
4. **Connect Oura.** Run `npm run oura-auth`. It stores the client credentials and the first token pair in SSM.
5. **Add the connector in claude.ai.** Go to Settings → Connectors → Add custom connector. Paste the output of `npm run url` and leave the OAuth fields empty.
6. **Set up Health Auto Export** as described above.

## Secrets (SSM SecureString, AWS-managed `aws/ssm` key)

| Parameter | Used for |
|---|---|
| `/oura-mcp/path-secret` | Path segment of the MCP URL (`/mcp/<secret>`) |
| `/oura-mcp/ingest-path-secret` | Path segment of the ingest URL (`/ingest/<secret>`) |
| `/oura-mcp/ingest-key` | Value of the `X-Ingest-Key` header on ingest |
| `/oura-mcp/oauth-client` | Oura client ID and secret |
| `/oura-mcp/tokens` | Oura access and refresh tokens; the Lambda rewrites them on each rotation |

## Refresh-token rotation (Oura)

Oura refresh tokens are single-use. The token manager in [src/tokens.ts](src/tokens.ts) handles this as follows:
- It refreshes 5 minutes before expiry, or after a 401.
- It re-reads SSM first, in case another instance has already rotated the tokens.
- It writes the new pair to SSM *before* using it.
- On `invalid_grant`, it polls SSM for the pair the winning instance saved.
- If the SSM write fails, it keeps the new pair in memory and retries the write.

Refreshes go to the token endpoint that issued the grant (`moi.ouraring.com` for current apps). If Oura revokes the grant, the tools tell you to run `npm run oura-auth`.

## Tests

- **`npm test`** runs offline, using the official MCP client against the Lambda handler through a fake Function URL. An in-memory store applies the same conditions as DynamoDB, so no test touches a real table.
  - **Oura:** the tools, both protocol eras, and refresh-token rotation, with a fake Oura that enforces single-use refresh tokens.
  - **Ingest:** HAE parsing, unit conversion, Oura filtering, auth, the size limit, the 415/400 responses, gzip and redaction.
  - **Health tools:** `log_reading` validation, the duplicate rule, and `delete_reading` (deleting chat readings; removing, undoing and re-sending Apple Health readings; ambiguous minutes).
  - **Nutrition and body measurements:** fat, fiber and net carbs, waist, body fat and lean mass: units, re-sends, reconciliation, delete and undo.
  - **Report page data:** each section equals the individual tool's payload, sleep periods fetched once, per-section errors (an Oura collection refused, a revoked Oura grant, the health table failing), the 366-day limit.
  - **Workouts:** both export versions, the fallbacks for energy and heart rate, the workout's own source (object or name, never the samples'), Oura workouts hidden when another app recorded the same session (and kept otherwise), re-sends, reconciliation with the window guard, `get_workouts` end to end, and removing and restoring a workout.
  - **Re-sends and reconciliation:** stable sample keys, separate same-second samples, skip-unchanged, the 15-minute two-push rule, un-marking, the more-than-half skip, window edges, "Today" pushes, and metrics that are missing, empty or Oura-only.
  - **Connector:** `subscriptions/listen` refused at once (it used to hang the Lambda until the runtime exited).
- **GitHub Actions** runs the type check and `npm test` on every push and pull request ([.github/workflows/test.yml](.github/workflows/test.yml)).
- **`npm run smoke`** checks the deployed stack with curl and writes nothing: the auth rejection, the MCP handshake, the tool list, the prompt list (one prompt per tool except `get_report_data`), one Oura tool, and read-only calls to `get_health_metrics`, `get_workouts` and `get_report_data` (it prints counts and sizes, not readings).

## Cost

- **Lambda, SSM, KMS (`aws/ssm`) and CloudWatch Logs** stay within always-free limits, as before. Logs are kept for 14 days.
- **DynamoDB on-demand** isn't covered by the always-free tier, which applies to provisioned capacity. At personal volumes it costs fractions of a cent a month, since writes cost well under $1 per million and storage is under 25 GB free.

The account-wide **monthly AWS Budget** (`BUDGET_LIMIT_USD` in `deploy.env`) emails `BUDGET_EMAIL` at 50% and 100% of actual spend, and at 100% of forecast spend. Change the amount there and re-run `npm run deploy`.

## Operations and decisions

- **Operating it** (logs, redeploying, rotating a secret, restores, the size limit, tearing it down) is in [docs/RUNBOOK.md](docs/RUNBOOK.md). URL secrets, the ingest key and tokens are never logged.
- **Why it is built this way,** and what is still undecided, is in [docs/DECISIONS.md](docs/DECISIONS.md). Every decision that changes behavior, cost or security gets an entry there.

## Licence and security

MIT; see [LICENSE](LICENSE). To report a security problem, see [SECURITY.md](SECURITY.md).