Skip to main content
Glama
Vaultbeat MCP Server

Vaultbeat MCP Server

Vaultbeat Apple Health MCP Server

Vaultbeat MCP server on Glama mcp.market grade Listed on mcpservers.org

Your Apple Health data — sleep stages, cycle, HRV, resting heart rate, workouts, weight, VO₂ max, meals, lifts, notes, symptoms, moods (State of Mind) — readable and writable by your own AI agent (Claude Code, Claude Desktop, Codex, Hermes, OpenClaw, anything that speaks MCP), end-to-end encrypted so that only your machine ever sees plaintext.

The Vaultbeat iPhone app reads HealthKit and encrypts every record on the phone. This package is the local server your agent talks to: it downloads the ciphertext, decrypts it on your machine, and serves it over MCP.

iPhone (HealthKit → Vaultbeat app, encrypts) ──► cloud (ciphertext only) ──► this server (decrypts locally) ──MCP──► your agent

The cloud stores ciphertext it cannot read. The key that opens it is generated on your machine when you pair, and never leaves it.

Requirements

  • The Vaultbeat iOS app, 1.2.3 or newer, signed in — App Store

  • uv (for uvx). The server needs Python 3.11+, and uvx downloads a suitable interpreter by itself if your system Python is older.

  • Vaultbeat Pro for agent access. Pairing a machine starts a 3-day trial of the AI interface; after that, reads and writes need Pro, bought in the iOS app (Settings → Membership). When access lapses nothing is deleted, and buying Pro resumes this machine without re-pairing.

How much history this server can read is decided by what the app uploads. With Pro, that is your whole history. A trial uploads your whole history on app 1.2.9 and later, and your last 7 days on 1.2.8 and earlier. Without either, app 1.2.8 and earlier upload your last 7 days and app 1.2.9 and later upload nothing. So a short history is usually a plan boundary, not a sync delay — vaultbeat_doctor tells the causes apart.

Related MCP server: apple-health-shortcuts-mcp

Quick start

1. Pair this machine with your iPhone.

uvx vaultbeat-apple-health@latest bind

It prints a QR code and waits. In the Vaultbeat app open MCP tab → Connect an AI server (app 1.2.8 and earlier: Settings → Data & AI) and scan it. The command waits 5 minutes (--timeout to change); once scanned there are 10 minutes to finish.

2. Add the server to your MCP client.

Claude Code, as a plugin (adds the server and a setup guide that walks Claude through pairing):

/plugin marketplace add Fino-wind/vaultbeat-apple-health
/plugin install vaultbeat-apple-health@vaultbeat

Then run /vaultbeat-apple-health:setup. Or add only the server:

claude mcp add vaultbeat-health -- uvx vaultbeat-apple-health@latest serve --transport stdio

Claude Desktop — add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and restart it:

{
  "mcpServers": {
    "vaultbeat-health": {
      "command": "uvx",
      "args": ["vaultbeat-apple-health@latest", "serve", "--transport", "stdio"]
    }
  }
}

Claude Desktop does not inherit your shell's PATH. If it reports that uvx cannot be found, put the absolute path from which uvx in "command".

Any other MCP client: run uvx vaultbeat-apple-health@latest serve --transport stdio as a stdio server. The @latest matters — without it uvx keeps running whichever version it cached first.

3. Check it works. Ask your agent to call vaultbeat_doctor, or run:

uvx vaultbeat-apple-health@latest doctor

It checks the config, the private key, cloud reachability, the pairing and a real fetch-and-decrypt round trip, and lists which data types have nothing to read yet. Right after pairing the phone is still sealing your history for the new machine, so a few kinds may be empty for a while; MCP tab → Re-sync all health data to AI in the app (app 1.2.8 and earlier: Settings → Data & AI) speeds it up.

Try it without an iPhone

uvx vaultbeat-apple-health@latest --demo doctor
uvx vaultbeat-apple-health@latest --demo serve --transport stdio   # wire this into a client

--demo is a global flag — it goes before the subcommand — and serves a fixed synthetic dataset: no pairing, no cloud, no key. Every result says demo_mode: true and carries a [SYNTHETIC DEMO DATA] banner, and the log_* write tools refuse.

MCP tools

29 tools. Reads return your own data — the account that paired this machine. Tools marked partner also take partner=true to read what your partner chose to share with you in their app — sleep, water and weight, and cycle, symptoms, moods and notes only if they turned that on. The two people are never mixed in one result. Every read tool takes fresh=true to skip the local cache.

Diagnostics

Tool

What it does

vaultbeat_doctor

Diagnose this install end to end, report which data types have no data and the likely reasons, and show the pairing state. The tool to call before telling anyone their data is missing.

Health records

Tool

What it returns

get_sleep_nights partner

Every night as one compact row: bed and wake time, asleep, deep / REM / core / awake, awakenings, longest unbroken sleep, heart and breathing rate while asleep, naps. A year fits in one call; since="YYYY-MM-DD" for a calendar window.

get_sleep_detail partner

One or two nights in depth: stage intervals with per-stage heart and breathing rate. The newest nights, or any night by date (since / until).

get_menstrual_cycle partner

Cycle samples and a next-period prediction. Sensitive.

get_symptoms partner

Symptoms from Apple Health, and beside them the episodes a person reported (type, severity, onset and end, place, suspected triggers). Sensitive.

get_state_of_mind partner

Moods — Apple Health's State of Mind: how pleasant each feeling was (valence and Apple's seven regions), Apple's feeling words and life areas, from the Watch, the Health app or other apps, and the ones an AI recorded; per-day count and average. The 100 newest by default, or a since / until window for older ones. Sensitive.

get_notes partner

Free-text notes on days, with who wrote them. Sensitive.

get_strength_log

Strength sessions: exercises, sets × reps, volume per session.

get_food_log

Meals and items per day, with optional kcal / protein / fat / carbs. The 14 newest days that have a log by default (not a calendar fortnight), or a since / until window.

get_workouts

Workouts: type, duration, calories, distance.

get_user_profile

Sex, age, date of birth and height. Needs Vaultbeat for iOS 1.2.9 or later.

Daily numbers and analysis

Tool

What it returns

get_metric partner

Per-day values for one series, several, or all of them: sleep duration, timing and stages, resting HR, HRV, wrist temperature, VO₂ max, weight and body composition, water, steps, active / basal / total energy, exercise and stand minutes, distance, mindfulness. aggregation (avg / sum / min / max / latest) and granularity (day / week / month / weekday) are computed server-side; since / until for a calendar window. Today on an accruing series is marked partial and kept out of aggregates.

get_intraday

Samples within a day, for HRV: one row per hour that has samples (granularity="hourly") or one per sample ("raw"). About 8–14 rows a day; limit counts rows.

list_metric_series partner

Every series name the tools above and below accept, with its unit and how much data backs it.

get_metric_trend partner

Least-squares slope, endpoints, mean / median / min / max.

compare_metric_periods partner

The newest N days against the N before them, or two named windows.

correlate_metric_series partner

Pearson r between two series over the days that have both; lag_days pairs a day with a later one.

The analysis tools return numbers only — no scores, grades or verdicts — and refuse rather than fit a line to two points.

Writes — all into the account that paired this machine, and nowhere else.

Tool

What it does

log_food_append / log_strength_append / log_note_append

Add to a day. Cannot delete anything — the safe default when a day may already have entries.

log_food_entry / log_strength_entry / log_note

Replace that whole day with what is passed, and report exactly what was removed.

log_weight_entry

Record a weigh-in, keeping that day's body composition.

log_symptom

Record one symptom the person reports, as structured fields a later read can match against sleep, food and heart rate.

update_symptom / delete_symptom

Change a reported symptom (usually its end time), or erase one logged by mistake.

log_state_of_mind

Record how the person says they feel, in Apple Health's State of Mind vocabulary (valence, feeling words, life areas). Their iPhone writes it into Apple Health only if they turned on "Allow AI to update Apple Health" (iOS app 1.3.0 or later).

delete_state_of_mind

Erase a mood an AI recorded by mistake; the iPhone also removes the copy it wrote into Apple Health.

log_note and log_note_append take partner=true to record a note about your partner. It stays in your own account, is never sent to them, and is kept apart from your own notes.

Reading the results

  • Every read carries a coverage block. days_covered is how many distinct days the answer rests on — quote it beside any average or trend. more_available: true means older records exist and your limit stopped short of them (oldest_available says how far back they go); it is never a sign of missing data.

  • Results are bounded. A result larger than about 60 KB is not sent; the tool returns result_too_large with a suggestion for narrowing the request (a smaller limit, a since date, one series instead of all). get_metric and get_intraday return their rows as a compact table (columns + rows).

  • Unknown arguments are rejected. A misspelled or retired parameter is an error, never silently ignored.

MCP prompts

The server also serves eight prompts over prompts/list — daily_brief, sleep_review, energy_balance, training_block_review, cycle_aware_read, partner_check_in, log_from_conversation and why_is_this_empty. Each names the tools to call and carries the same two rules: say what the data covers before concluding, and treat an empty result as something to explain (it has several possible causes), never as a zero. Every argument is optional.

Privacy and security

  • Decryption happens only on this machine. The cloud holds ciphertext and per-recipient wrapped keys; the private key that opens them is generated here when you pair.

  • Health data leaves this package only through MCP. The command-line subcommands pair a machine, report on that pairing and start the server; none of them prints health data.

  • Sensitive categories. Your cycle and the symptoms Apple Health records reach this server only after you turn them on, per category, in the iOS app — they are off by default. Your notes, your moods (State of Mind, from Apple Health and from log_state_of_mind) and the symptoms you report yourself (in the app, or through log_symptom) are always readable by your own agent. None of these reaches your partner's agent unless you turn on sharing it with them.

  • Unpair at any time from the app's MCP tab (app 1.2.8 and earlier: Settings → Data & AI); the machine can then decrypt nothing new.

  • Tool results never contain the private key or the server token.

Where the private key lives

Not in config.json. It is looked for in this order:

  1. the VAULTBEAT_PRIVATE_KEY environment variable, if set (read, never written back) — for operators injecting it from a secret store;

  2. the system keyring — the normal case on a desktop;

  3. ~/.tether/mcp-local/identity.key, mode 0600 — the automatic fallback on a machine with no keyring.

~/.tether/mcp-local/config.json (mode 0600) holds the cloud-issued server token and your public key. .tether is the app's former name and the path is kept on purpose: existing installs find their key through it.

Never delete config.json to "start clean". The private key is not in it, so deleting does not clear a bad key — it mints a new identity, and every record already encrypted for the old one becomes permanently unreadable. To repair a pairing, run bind again: it re-pairs this machine in place and keeps what is already encrypted for it.

Headless servers. If the keyring is unreachable, let the identity.key fallback handle it — it engages by itself. Do not set PYTHON_KEYRING_BACKEND to the null backend: it accepts writes and stores nothing, so it only hides a keyring you might be able to reach. If a D-Bus session exists but this process cannot see it (common when the server is started by an agent framework, systemd or cron), pass DBUS_SESSION_BUS_ADDRESS through explicitly — resolve it first (echo "unix:path=/run/user/$(id -u)/bus") and put the literal result in the client's env block, since that block is JSON, not a shell.

Telemetry

The server sends usage events to PostHog (EU): which tool was called, whether it succeeded, a duration range, and the AI client and package versions — tied to the account this machine is paired to. Tool arguments, results and health data are never sent. Set VAULTBEAT_TELEMETRY=0 (or DO_NOT_TRACK=1) to turn it off. Details: vaultbeat.app/privacy.

Troubleshooting

Start with doctor. uvx vaultbeat-apple-health@latest doctor prints an [OK] / [FAIL] list with a fix for the first thing that is broken; doctor --json is the same report for an agent. Exit code 0 means healthy.

A read comes back short or empty. Read coverage.more_available first: true means your limit was the boundary — ask for more. false with a short history is the plan boundary described under Requirements, or a pairing that is still filling in. vaultbeat_doctor lists the kinds with no data and the possible reasons for each.

The QR code looks wrong (mojibake or uneven rows — usually Windows with a non-UTF-8 code page). The pairing is still waiting, so do not re-run bind: that replaces the code on screen. Instead render the JSON payload printed just above the code as an image (qrencode -o pair.png '<payload>'), send it to your phone and use import from Photos in the app's scanner; or run chcp 65001 in a fresh terminal; or use bind --no-qr for the payload as text.

Reads fail with an access message. The trial or Pro membership has lapsed. Nothing has been deleted; buying Pro in the iOS app (Settings → Membership) resumes this machine without re-pairing.

HTTP transport

For clients that connect over a network instead of launching a subprocess:

vaultbeat-apple-health serve --generate-token            # mint and store a bearer token, print client config
vaultbeat-apple-health serve --transport http            # 127.0.0.1:8000/mcp, bearer token required

The token is read from VAULTBEAT_MCP_HTTP_TOKEN (preferred, keeps it out of shell history) or the stored config, and clients send it as Authorization: Bearer <token>. --show-token prints the stored one. --no-token serves loopback without auth.

Binding beyond loopback (--host 0.0.0.0 for a LAN or VPS) fails closed: it needs both a token and --allow-remote. The token crosses the wire in clear text, so put TLS in front of it (Caddy, nginx, Cloudflare). Other flags: --sse-response for SSE-style responses, --stateful-http for clients that need sessions.

Example mcp.json (VS Code / Cursor style):

{
  "servers": {
    "vaultbeat-health": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

A client that only speaks stdio can reach the HTTP server through mcp-remote: npx -y mcp-remote http://127.0.0.1:8000/mcp --header "Authorization: Bearer <token>".

Reporting issues

This repo takes issues for both the MCP server and the Vaultbeat iPhone app — install failures, tool errors, binding that never completes, doctor reporting something wrong, and app problems too (UI, subscriptions, HealthKit permission prompts, sync not showing up on the phone). Open an issue and pick the template that fits. Questions and ideas can go in Discussions.

This is a public repo: never paste health data, pairing codes or account details.

Development

The command line has six subcommands, and none of them reads health data:

vaultbeat-apple-health bind      # pair this machine with the iOS app (QR)
vaultbeat-apple-health status    # local pairing state
vaultbeat-apple-health doctor    # self-diagnosis
vaultbeat-apple-health init      # generate a keypair and config without pairing
vaultbeat-apple-health poll      # poll once for a pending pairing
vaultbeat-apple-health serve     # run the MCP server (stdio or http)

Decrypted records are cached per data type under ~/.tether/mcp-local/cache/ (files 0600, directory 0700) for 600 seconds; VAULTBEAT_MCP_CACHE_TTL overrides it (0 disables). After the first read, a refresh downloads only the records that changed. Pairing to a different server identity clears the cache.

Run the checks from a clone:

uv sync --frozen --all-extras
uv run --frozen pytest -q tests
uv run --frozen ruff check src tests
uv run --frozen mypy src

vaultbeat-mcp and vaultbeat-mcp-local remain as console-script aliases for installs from before the package was renamed vaultbeat-apple-health (0.6.2).

Available Tools

29 tools
compare_metric_periodsCompare two periodsA
Read-onlyIdempotent

Compare two periods of one series: the newest days vs the days before, or two named windows.

To compare CALENDAR periods — "this semester vs the summer", "before and after I started training" — pass period and baseline, each "YYYY-MM-DD..YYYY-MM-DD" (an open end is allowed: "2026-09-01.."). days is then ignored. Without them, the rule below applies.

"Before" means the next-oldest days WITH DATA, so a gap makes the earlier window older rather than emptier — read previous.first_day / previous.last_day to see which period you actually got, and quote them.

Returns both windows' mean/median/min/max and the differences. It does not say which window is better; that depends on the metric and on the person.

Carries a coverage block over the days the arithmetic used: quote coverage.days_covered and coverage.span_days beside any number here. coverage.window_satisfied: false alone does NOT mean a short history — it is also false when older days exist beyond the window; coverage.more_available tells the two apart.

Inputs: series (required), days, fresh, period, +2 more. Returns: object

correlate_metric_seriesCorrelate two seriesA
Read-onlyIdempotent

Pearson r between two daily series, over days that have BOTH recorded.

lag_days pairs series_a on each day with series_b that many days LATER (negative = earlier): "does a short night show up in HRV the day after" is sleep vs HRV with lag_days=1. Sleep is already dated by the morning it ends, so lag 0 is "last night vs today". since / until ("YYYY-MM-DD") restrict to a calendar window.

Days missing on either side are dropped, never interpolated and never read as zero, so n_pairs is usually smaller than either series — quote it with r. Fewer than 3 shared days returns null with a reason: any two points are perfectly collinear, so a coefficient there is an artefact.

The result carries a caveat field about causation. Repeat its substance in your answer, and do not translate r into a word like "strong".

Carries a coverage block over the days the arithmetic used: quote coverage.days_covered and coverage.span_days beside any number here. coverage.window_satisfied: false alone does NOT mean a short history — it is also false when older days exist beyond the window; coverage.more_available tells the two apart.

Inputs: series_a (required), series_b (required), days, fresh, +4 more. Returns: object

delete_state_of_mindDelete state of mind (erases the entry)A
Destructive

Erase one state of mind an AI recorded by mistake (agent write).

Only for an entry that should never have existed — a duplicate, the wrong reading of what they said, the wrong person. To record that a feeling changed, log a new one; feelings change and both are true.

It disappears from get_state_of_mind at once. The person's iPhone, on its next sync, drops it from the app, overwrites its content in the cloud for every reader it was shared with, and removes the sample it wrote into Apple Health, if it wrote one. The result carries deleted_entry — the full entry as it was — so a mistaken delete can be logged again. Records with source: "apple_health" cannot be deleted here; they are edited in Apple Health.

Inputs: entry_id (required). Returns: object

delete_symptomDelete symptom (erases the entry)A
Destructive

Erase one reported symptom that was logged by mistake (agent write).

Only for an entry that should never have existed — a duplicate, the wrong person, a symptom they did not have. A symptom that simply ended is NOT deleted: record its end with update_symptom(entry_id, end_at=…).

It disappears from get_symptoms at once, and from the app and every other reader once the person's iPhone next syncs (it then overwrites the entry's own copy in the cloud, and from app 1.3.0 removes the copies earlier update_symptom calls left; an older app leaves those sealed there, readable only by the person and the server that wrote them). The result carries deleted_entry — the full entry as it was — so a mistaken delete can be logged again with log_symptom. Symptoms imported from Apple Health cannot be deleted here.

Inputs: entry_id (required). Returns: object

get_food_logFood logA
Read-onlyIdempotent

Decrypt daily food-intake logs locally (newest first).

limit counts LOGGED days: by default the newest 14 days that have a log — not a calendar fortnight. Days with nothing logged are skipped, so the 14 can reach further back; coverage.span_days and coverage.days_missing_in_span say how far. since / until ("YYYY-MM-DD", local days, both inclusive) read a calendar window instead — "what did I eat in the first week of August" — and then limit applies only if you pass it. Each day's date is its local calendar day (the same as local_date, and the form log_food_entry and get_strength_log use). A logged day is roughly 0.5-1k tokens (more with notes, and Chinese text counts more), so a month can already be past what a client takes in one result — it then comes back as result_too_large; ask for fewer days or a narrower window.

Each day carries meals, each meal a list of items with food (name), optional free-text portion ("1 根" / "300g" / "小份"), optional per-item/per-meal note, and — when the logging agent estimated them — optional structured nutrition numbers (kcal, proteinGrams, fatGrams, carbGrams). Items without those fields need analysis-time estimation from name + portion; items with them can be summed directly. Owner's own days only. Pass limit_days to cap how many days return.

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit, since, until, +1 more. Returns: object

get_intradayIntraday samplesA
Read-onlyIdempotent

Samples WITHIN a day, for the series that record several per day (HRV).

granularity:

  • "hourly" (default) — one row per hour that HAS samples (UTC hour boundaries, shown in local time), the mean SDNN of that hour and its sample_count. Right for "how did my HRV move through the day".

  • "raw" — one row per sample, newest first.

The Watch measures HRV a handful of times a day, not continuously (more during a Breathe session), so most days have about 8-14 rows either way. limit counts ROWS, not days: the default 168 is roughly two to three weeks, not one. How far back the history goes depends on what this phone uploaded, not on a fixed window — read coverage.oldest_available and coverage.more_available. For one number per day use get_metric. Reads YOUR data only: HRV is never shared between partners.

rows is a table in columns order (local_time, sdnn_ms, plus sample_count for hourly). Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) beside any number.

Inputs: fresh, limit, series, granularity. Returns: object

get_menstrual_cycleMenstrual cycleA
Read-onlyIdempotent

Decrypt recent menstrual cycle data locally and predict the next period.

SENSITIVE: menstrual data only reaches this server if the user explicitly opted in on iOS; it stays on-device and is never re-exported. Returns recent samples plus a next-period prediction. Reads YOUR cycle by default; if the cycle being asked about is your partner's, pass partner=true (it reaches this server only if they share it).

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit, partner. Returns: object

get_metricDaily health metricsA
Read-onlyIdempotent

Read any one-number-per-day health series: steps, resting HR, HRV, weight, …

series takes ONE name, a LIST of names, or nothing (= every series). Names come from list_metric_series, which also says how much data backs each — call it first rather than guessing. Activity is five series (steps, active_energy, exercise_minutes, stand_minutes, distance_meters); pass them as a list to get the whole day in one call.

days = the newest N days THAT HAVE DATA, per series (not N calendar days). For a CALENDAR window — "last month", "this semester", "July" — pass since / until ("YYYY-MM-DD", either or both) instead; days is then ignored and the reply names the range it used.

aggregation is computed here, not by you: avg / sum / min / max / latest over the window, or none (default) for the per-day points only. sum is refused on state measurements (resting HR, weight, VO2max) — it has no meaning there. granularity = day (default), week (ISO weeks) or month; week/month return buckets aggregated with aggregation (avg when none), each with days_with_data beside days_in_period. period_in_progress: true marks the current, unfinished week/month and clipped_by_window: true the oldest one your days cut through — never compare either against a full period as if it were one. granularity = weekday groups the window by day of the week (Mon..Sun) — the direct answer to "weekends vs weekdays" and to social jet lag. Read its weekday_note: sleep is dated by the morning it ends, so Sat is the Friday-night sleep.

Honesty the reply already does for you, so do not undo it: · On cumulative series (steps, energy, water) today is still accruing — it is marked partial: true and excluded from every aggregate. · excluded_days names days dropped because their data was short (basal energy with the Watch off the wrist, TDEE without basal), with reasons. · Missing days are absent, never zero.

Each series' points (or buckets) is a table: columns names the fields once and every entry of rows is one day (or period) in that order — e.g. columns: ["date", "value", "partial"]. The flags above are columns; a day without one has null there.

Each series carries its own coverage block: quote coverage.days_covered and coverage.span_days beside any number. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means older days exist that your days left behind — ask for more, or quote coverage.oldest_available. Never report a window as the extent of their data.

Reads YOUR data by default. Pass partner=true for your partner's — of these series only sleep, water and weight (with body composition) can be shared, so every other series comes back empty for a partner by design.

Sleep is here too — duration, timing (bedtime_minutes, wake_minutes, sleep_midpoint_minutes), stages, awakenings, heart/breathing rate while asleep; the nights behind those numbers are get_sleep_nights. Richer kinds have their own tools: workouts, strength, food, notes, symptoms, cycle, and the sex / age / height profile (get_user_profile). Samples within a day (HRV spikes) → get_intraday. Trend / period comparison / correlation → get_metric_trend, compare_metric_periods, correlate_metric_series.

Inputs: days, fresh, since, until, +4 more. Returns: object

get_metric_trendMetric trendA
Read-onlyIdempotent

Least-squares trend for one daily series: slope per day, endpoints, spread.

series is a name from list_metric_series. days selects the newest N days THAT HAVE DATA, not the last N calendar days — compare n_days with span_days to see whether the history is dense or sparse. since / until ("YYYY-MM-DD") fit a calendar window instead.

Returns arithmetic only. slope_per_day is in the series' own unit per day and carries no threshold, band or verdict; fewer than 3 days returns a null slope with a reason rather than a number fitted to noise.

Carries a coverage block over the days the arithmetic used: quote coverage.days_covered and coverage.span_days beside any number here. coverage.window_satisfied: false alone does NOT mean a short history — it is also false when older days exist beyond the window; coverage.more_available tells the two apart.

Inputs: series (required), days, fresh, since, +2 more. Returns: object

get_notesNotesA
Read-onlyIdempotent

Decrypt recent free-text notes (day annotations) locally.

SENSITIVE free text. Each note carries owner_user_id (who wrote it), target_kind, and target_date (the local day it annotates) — join against the same-day metric data for pattern analysis. Kinds: "sleep" | "menstrual" are written manually in the iOS app by either partner (e.g. "昨晚舍友很吵" on a sleep day), and "day" is what the person wrote about the day itself in the app's notes list (app 1.3.0+); "general" is agent-authored via log_note; "mood" notes are ones an AI wrote before moods moved to get_state_of_mind — read them here, write no new ones. Pass target_kind to filter. Stays on-device, never re-exported.

Returns notes about YOU by default. partner=true returns notes about your partner: the ones they wrote themselves and shared, plus the ones your AI recorded about them (about: "partner", written with log_note_append(partner=true)).

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit, partner, target_kind. Returns: object

get_sleep_detailSleep stage detailA
Read-onlyIdempotent

Per-night sleep stages with per-stage HR/RR — depth on a few nights.

Which sleep tool to use: · THIS one for going deep on one or two specific nights (stage bands, per-stage vitals). It defaults to 2 nights because each is ~3k characters; see the SIZE note below. · get_sleep_nights for anything spanning time — "how did I sleep this week/month/year", patterns, worst nights. One compact row per night, a whole year in one read. Reach for it whenever the question is about a period rather than a night, and do not conclude from THIS tool's two rows that only two nights exist. · get_metric with the sleep series (bedtime_minutes, deep_sleep_minutes, awakenings, ...) for averages computed for you.

(This used to call itself "the primary tool for detailed sleep analysis", which read as "use this one for sleep" and handed back two days to anyone who asked how their week went.)

Returns stage_intervals (contiguous stage bands with start/end), stage_minutes, and stage_vitals (per-stage HR/RR min/mean/max). Reads YOUR nights by default; partner=true reads your partner's shared sleep.

limit = the newest N nights, 2 by default. To read a particular night, pass its date as since and until ("YYYY-MM-DD", the local day the night ENDS on — the local_date / date column of get_sleep_nights); a wider since / until reads every night in that window, and limit then applies only if you pass it.

⚠️ SIZE: each night is ~3k characters as returned (a week ~21k). Setting include_timeline=True adds the raw per-sample array (hr, rr, stage, time) — about 13k characters PER NIGHT, which will overflow a typical 25k-token client budget after 2-3 nights. Ask for it only when you need sample-level vitals (e.g. "when exactly did HR spike"); stage_vitals already answers per-stage questions. Raise limit for trends, but keep it low whenever include_timeline=True.

⚠️ is_in_bed_only: true means sleep was NEVER MEASURED that night (the Watch wasn't worn) — NOT that the person slept zero. duration_label reads "no sleep data" and in_bed_minutes holds the time actually recorded in bed. Report it as "no sleep data (in bed ~Xh)", never as "slept 0 hours".

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit, since, until, +2 more. Returns: object

get_sleep_nightsSleep, every nightA
Read-onlyIdempotent

Every night as one compact row — the tool for reading a sleep HISTORY.

One row per night, newest first: date, weekday, bed and wake time, time asleep, deep / REM / core / awake minutes, deep and REM share, number of awakenings, longest unbroken stretch of sleep, heart and breathing rate while asleep, and any OTHER sleep that day (naps, the second half of a broken night) — so a day's total sleep is asleep plus other. Column names come once in columns; each row is the values in that order, so a whole year is ~40k characters. Read it when the question is about a period or a pattern: weekends vs weekdays, drifting bedtimes, which nights were worst, what changed after a date.

Which sleep tool: · THIS one for any span of time. · get_metric with the sleep series (sleep_minutes, bedtime_minutes, deep_sleep_minutes, awakenings, ...) when you want the arithmetic — weekly/monthly averages computed for you, from these same rows. · get_sleep_detail for one or two nights in depth (stage bands, per-stage vitals).

limit = newest N nights (default 120; pass 400 for everything, and check coverage.more_available). since = "YYYY-MM-DD" keeps every night on or after that day — use it for "last month" rather than guessing a limit; with since, limit applies only if you pass it.

Read legend once. Five flags, comma-separated when a night has several: unworn means sleep was never measured that night (not zero sleep), motion_inferred means phone motion guessed it (leave it out of averages, as get_metric does), daytime means the day's only sleep was a daytime nap (real, but not a night — out of get_metric's nightly series, still a row here), short means a main sleep under 3 h with no stages — a nap or a partly recorded night, left out of get_metric's sleep-duration and clock series — and no_stages means the total is known but the stage columns are null. A null anywhere is "not measured", never zero. Reads YOUR nights; partner=true reads your partner's shared sleep.

Carries a coverage block: quote coverage.days_covered beside any average, and read coverage.more_available before saying how far back the history goes.

Inputs: fresh, limit, since, partner. Returns: object

get_state_of_mindState of mind (moods)A
Read-onlyIdempotent

Decrypt recent states of mind (how the person felt) locally — both sources.

SENSITIVE. Apple Health's "State of Mind": each record is one feeling with valence (-1 very unpleasant … 0 neutral … +1 very pleasant), valence_classification (Apple's seven regions, veryUnpleasant … veryPleasant — use these words rather than inventing a grade), labels (Apple's feeling words: drained, stressed, calm, grateful…), associations (the life area: work, family, partner, health…), kind (momentaryEmotion = how they felt at that moment, dailyMood = how the day went overall), local_date / local_time. source says where it came from: · "apple_health" — logged by the person on their Watch, in the Health app or in another app, and imported by their iPhone (app names it); · "ai" — recorded by an AI through log_state_of_mind (entry_id, note). Remove a mistaken one with delete_state_of_mind. Each owner also carries daily (per day: count, mean_valence, lowest_valence, highest_valence, daily_mood_valence) and counts per region, label and life area. Describe what was logged; a day with one record says far less than a day with ten — quote count beside any average, and never read a day with no record as a neutral day.

By default the newest 100 records (about three months of daily moods). since / until ("YYYY-MM-DD", local days, both inclusive) read a calendar window instead — "how was I in March", or anything older than the default page — and then limit applies only if you pass it. A record with its tallies is roughly 450 bytes, so about 130 fit in one result; a longer window comes back as result_too_large — read it a month or a quarter at a time.

Returns YOUR records by default; partner=true returns your partner's — only if they turned on sharing their moods with your AI in their own Vaultbeat app (off by default). Stays on-device, never re-exported.

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt records OLDER than first_day that your read left behind — read them with a since / until window ending before first_day (a much larger limit does not fit in one result), or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit, since, until, +1 more. Returns: object

get_strength_logStrength logA
Read-onlyIdempotent

Decrypt recent strength-training sessions locally (newest first).

Exercise-level detail HealthKit's workout type cannot carry: each session lists exercises with their sets (weightKg × reps), an optional session note, and total_volume_kg (Σ weight × reps). Logged manually in Vaultbeat; owner's own sessions only — strength has no partner fan-out. Join date against sleep/HRV/weight for training-load analysis. Pass limit_days to cap how many sessions return. duplicate_sessions, when present, lists stored entries that only repeat another session of the same day; they are already left out of sessions and session_count, so do not add their volume back.

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit, limit_days. Returns: object

get_symptomsSymptomsA
Read-onlyIdempotent

Decrypt recent symptoms locally, grouped by data owner — both sources.

SENSITIVE. Each entry in owners carries owner_user_id and two lists: · days — symptoms imported from Apple Health (cramps, headache, fatigue, coughing…), one row per day with each sample's severity (mild/moderate/severe/present/…). These reach this server only when the user opted in on iOS — their own AI toggle, or the partner-AI toggle for a partner's. symptom_counts counts logged DAYS per type. · reported — episodes a person reported themselves, through log_symptom or the Vaultbeat app: entry_id, symptom_type, display_name (their own words), severity, local_date, onset_at / end_at (end_recorded: false means no end was logged — ask, do not assume it is still going), duration_minutes, body_location, triggers, note. reported_counts counts EPISODES per type. A type that exists in Apple Health is spelled the same in both lists (healthkit_type: true), so "headache" from either source is one symptom. To correct or remove a reported entry use update_symptom / delete_symptom with its entry_id; imported days are edited in Apple Health. Stays on-device, never re-exported.

Returns YOUR symptoms by default; partner=true returns your partner's Apple Health days only (if they share symptoms with you from their own app). A partner's reported episodes never reach you: the app and log_symptom seal them for their owner's own AI alone, so an empty reported under partner=true means "not shareable", not "none logged".

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data. limit cuts each list on its own: that many imported days AND that many reported entries, so a day with three reports can come back with one.

Inputs: fresh, limit, partner. Returns: object

get_user_profileHealth profileA
Read-onlyIdempotent

Read YOUR health profile: biological sex, age, date of birth, height.

Use it before anything that depends on sex, age or height — basal metabolic rate, heart-rate zones, VO2 max bands, BMI. It is never shared between partners, so this tool has no partner option.

profile.sex_source says where the sex came from: "chosen" (the person picked it in the app) or "apple_health" (a field in Apple Health they may never have looked at). Every field may be null; profile itself is null when nothing was uploaded, and the reply's note explains why that cannot be narrowed down. Never fill a null in with a guess.

A profile is not a series: its coverage.days_covered is 0 by construction, and the reply carries no upload time — the stored row is replaced in place on every edit, so nothing here says how current the values are.

Inputs: fresh. Returns: object

get_workoutsWorkoutsA
Read-onlyIdempotent

Decrypt recent workout sessions (type, duration, calories, distance). Reads YOUR workouts; workouts are never shared between partners, so this tool has no partner option.

Carries a coverage block: quote coverage.days_covered (distinct days, not the row count) and coverage.span_days beside any average or trend. coverage.window_satisfied: false alone does NOT mean a short history: it is also false when older days exist beyond your window. 🔴 Before saying how far back someone's data goes, read coverage.more_available: true means this server can decrypt days OLDER than first_day that your limit left behind — re-read with a larger limit, or quote coverage.oldest_available as the real start of their history. Never report a limit-shaped window as the extent of their data.

Inputs: fresh, limit. Returns: object

list_metric_seriesList analysable seriesA
Read-onlyIdempotent

Every series, with how much data actually backs each one.

Call this BEFORE guessing a series name, and before concluding a kind is empty. Each row carries rows / first_date / last_date / latest, so "does this person track VO2max at all" is answered here in one call instead of by reading the kind and getting nothing back.

rows = the days that HAVE a value for that series — counted the way get_metric reads it, so rows: 2 means get_metric can return at most 2 points. A kind's series can differ: a partner with 14 weigh-ins may have a BMI on only 2 of those days.

cumulative: true marks the series whose daily value ACCRUES over the day (steps, energy, water). On those the newest value is routinely a partial day and must not be compared against completed ones — that is what makes "steps are down today" wrong at 9am. Measurements of a state (resting HR, VO2max) carry false and need no such care.

Sleep appears here as numbers (duration, timing, stages, awakenings, vitals); read the nights themselves with get_sleep_nights. Kinds with a richer shape (workouts, strength sets, food, notes, symptoms, cycle) are deliberately absent — flattening them to one number per day would answer a question you did not ask; read them with their own tool.

Inputs: fresh, partner. Returns: object

log_food_appendAdd to food logA

Add meals to a day WITHOUT touching what is already logged (agent write).

This tool cannot delete anything you did not send. Your meals are appended to whatever the day already holds; a meal whose name matches an existing meal gets its items appended to that meal. This is the right tool for "log the snack I forgot" / "add dinner to today" — which is almost every follow-up write of the day.

Reach for log_food_entry ONLY when you intend the supplied meals to become the day's ENTIRE log and everything else to be deleted.

date is the LOCAL calendar day, "YYYY-MM-DD". meals is a list of {name?, timeOfDay?, items: [...], note?} where each item is {food, portion?, note?, kcal?, proteinGrams?, fatGrams?, carbGrams?}, e.g. [{"name": "lunch", "items": [{"food": "香蕉", "portion": "1 根", "kcal": 105}]}]. Everything but food is optional so a rushed "just log 香蕉" still works; when you DO estimate nutrition at logging time, put the numbers in the structured fields (snake_case aliases like protein_g are accepted) — they persist for later sessions instead of being re-guessed each read.

ESTIMATING FROM A PHOTO: look for something of known size in the frame first — a utensil, a hand, a coin, the rim of a standard plate — and calibrate the portion against it. With no such reference an image cannot settle portion size, and portion size is what the whole estimate rests on. In that case say so in your reply and give a range rather than a precise-looking number. These values are persisted and summed into daily totals later, so a confident "650 kcal" that is wrong does more damage than "roughly 500-700, nothing in frame to judge size by" — the first silently poisons a week of trends, the second invites a correction. [keep the photo-estimation paragraph above in sync with log_food_entry's copy]

This tool deliberately cannot set the day's note: that field is replace-only, and a tool that promises to delete nothing must not carry an exception. Use log_food_entry to change it.

The result is the same shape log_food_entry returns. replaced_meals is always [] here — that empty list is the receipt that this call deleted nothing. Encrypted end-to-end before it ever leaves this machine.

Inputs: date (required), meals (required). Returns: object

log_food_entryLog food (replaces day)A
Destructive

Log one day's food intake on the owner's behalf (agent write).

⚠️ THIS TOOL DELETES. The supplied meals become the day's ENTIRE log — any meal you don't re-send is silently deleted. If you meant to ADD to a day rather than replace it, STOP and call log_food_append instead; it cannot delete anything.

(merge=True still does the same thing as log_food_append and keeps working for callers that already use it. New callers should use the separate tool: which one you called is visible to the owner, a flag buried in the arguments is not.)

The result carries replaced_meals — the meals this call deleted. If that list is non-empty and you did not intend to replace the day, you just destroyed them; re-send them with merge=True.

note=None LEAVES THE EXISTING NOTE ALONE in both modes (pass note="" to clear it).

date is the LOCAL calendar day, "YYYY-MM-DD". meals is a list of {name?, timeOfDay?, items: [...], note?} where each item is {food, portion?, note?, kcal?, proteinGrams?, fatGrams?, carbGrams?}, e.g. [{"name": "lunch", "items": [{"food": "香蕉", "portion": "1 根", "kcal": 105}]}]. Everything but food is optional so a rushed "just log 香蕉" still works; when you DO estimate nutrition at logging time, put the numbers in the structured fields (snake_case aliases like protein_g are accepted) — they persist for later sessions instead of being re-guessed each read.

ESTIMATING FROM A PHOTO: look for something of known size in the frame first — a utensil, a hand, a coin, the rim of a standard plate — and calibrate the portion against it. With no such reference an image cannot settle portion size, and portion size is what the whole estimate rests on. In that case say so in your reply and give a range rather than a precise-looking number. These values are persisted and summed into daily totals later, so a confident "650 kcal" that is wrong does more damage than "roughly 500-700, nothing in frame to judge size by" — the first silently poisons a week of trends, the second invites a correction. [keep the photo-estimation paragraph above in sync with log_food_append's copy] Encrypted end-to-end before it ever leaves this machine.

Inputs: date (required), meals (required), note, merge. Returns: object

log_noteLog note (replaces note)A
Destructive

Log a free-text note on the owner's behalf (agent write).

For day events that belong next to the metric data instead of in chat history, worth joining against sleep/HRV later (kind="general", the default and the only kind this tool writes). A feeling does NOT go here, nor the story behind it: call log_state_of_mind, which keeps it as Apple Health's fields and has its own note for the why. This tool refuses kind="mood" — one feeling recorded twice, once structured and once as free text, is what that kind produced. (sleep, menstrual and day notes are written in the iOS app — refused too.)

⚠️ THIS TOOL DELETES. There is one note per (kind, day), and your text becomes its ENTIRE contents — anything already written for that kind+day is silently deleted. If you meant to ADD to a day rather than replace it, STOP and call log_note_append instead; it cannot delete anything.

(merge=True still does the same thing as log_note_append and keeps working for callers that already use it. New callers should use the separate tool: which one you called is visible to the owner, a flag buried in the arguments is not.)

The result carries replaced_text — the note this call deleted. If it is non-null and you did not intend to replace, you just destroyed that text; re-send it with merge=True.

Symptoms do NOT go here: use log_symptom, one call per symptom. A note is free text nothing can be matched against; a symptom entry keeps its type, severity and timing so it can later be lined up with sleep, food and heart rate. A note is for what surrounds it (events, how a day went).

date = LOCAL calendar day "YYYY-MM-DD" (default today). Read back via get_notes (optionally target_kind="general"). Encrypted end-to-end before it ever leaves this machine.

partner=true records a note ABOUT your partner ("she had a stomach ache this morning"). It is stored in YOUR account and sealed for you and your own AI machines only (the Vaultbeat app passes it on to your other paired machines) — never for your partner or their AI. Your partner's account is never touched, and it never mixes into your own notes: plain reads leave it out, get_notes(partner=true) returns it. Default false = a note about you.

Inputs: text (required), date, kind, merge, +1 more. Returns: object

log_note_appendAdd to noteA

Add a line to a day's note WITHOUT erasing what is already there (agent write).

There is one note per (kind, day). This tool appends your text to it on a new line and cannot delete what is already written.

The second note of a day is the normal case, not the exception — a morning event and an evening one — and log_note would replace the first with the second. Symptoms do NOT go here: use log_symptom, which keeps type, severity and timing as fields a later analysis can match.

Reach for log_note ONLY when you intend your text to become the note's ENTIRE contents and whatever is there now to be deleted (e.g. correcting something you yourself wrote a minute ago).

kind="general" (the default and the only kind it writes) for day events worth joining against sleep/HRV later. A feeling and the story behind it go to log_state_of_mind and its note; this tool refuses kind="mood", and sleep, menstrual and day notes are written in the iOS app. date = LOCAL calendar day "YYYY-MM-DD" (default today). Read back via get_notes.

The result is the same shape log_note returns. replaced_text is always null here — that null is the receipt that this call deleted nothing. Encrypted end-to-end before it ever leaves this machine.

partner=true records a note ABOUT your partner ("she had a stomach ache this morning"). It is stored in YOUR account and sealed for you and your own AI machines only (the Vaultbeat app passes it on to your other paired machines) — never for your partner or their AI. Your partner's account is never touched, and it never mixes into your own notes: plain reads leave it out, get_notes(partner=true) returns it. Default false = a note about you.

Inputs: text (required), date, kind, partner. Returns: object

log_state_of_mindLog state of mindA

Record how the person says they feel, as Apple Health's State of Mind (agent write).

This is where "今天工作好累,被掏空了" / "刚散步回来,心情特别平静" / "I'm so anxious about tomorrow" goes when they tell you how they feel — people rarely open an app to log a feeling, but they say it to you. One call per feeling. This tool only ever adds; delete_state_of_mind removes a mistaken one.

valence: -1 (very unpleasant) … 0 (neutral) … +1 (very pleasant), YOUR reading of how pleasant it felt FROM THEIR WORDS. Apple splits the range into seven equal regions: about -0.85 very unpleasant, -0.55 unpleasant, -0.3 slightly unpleasant, 0 neutral, +0.3 slightly pleasant, +0.55 pleasant, +0.85 very pleasant. Stay inside what they said; do not dramatise "有点烦" into very unpleasant.

labels: Apple's feeling words that THEIR words support, usually one to three — amazed, amused, angry, annoyed, anxious, ashamed, brave, calm, confident, content, disappointed, discouraged, disgusted, drained, embarrassed, excited, frustrated, grateful, guilty, happy, hopeful, hopeless, indifferent, irritated, jealous, joyful, lonely, overwhelmed, passionate, peaceful, proud, relieved, sad, satisfied, scared, stressed, surprised, worried. Leave it empty rather than guess when they only said "心情还行". associations: what it is about, only if they said — community, current_events, dating, education, family, fitness, friends, health, hobbies, identity, money, partner, self_care, spirituality, tasks, travel, weather, work. kind: "momentaryEmotion" (default — how they feel right now or at one moment) or "dailyMood" (how the whole day has been). logged_at: the moment, ISO 8601 with their UTC offset, e.g. "2026-10-04T14:20+08:00"; omit it for right now. A dailyMood about a past day may give just that day as date ("2026-10-03") — do not invent an hour. note: a short summary in their words, only if useful later. It stays in Vaultbeat; Apple Health has no place for text.

The person's iPhone writes it into Apple Health (Mental Wellbeing → State of Mind) only if they turned on "Allow AI to update Apple Health" in the app — it is off by default; either way it shows in Vaultbeat's mood calendar (app 1.3.0 and later; an older app keeps it without showing it). Returns entry_id (for delete_state_of_mind) and the entry as read back. Read everything with get_state_of_mind. Encrypted end to end before it leaves here, for the owner and this machine; the owner's iPhone then re-seals it for their other paired machines and — only if they turned on sharing moods with their partner's AI — for that AI too, note included, so write nothing in note they would not want that reader to see.

Inputs: valence (required), date, kind, note, +3 more. Returns: object

log_strength_appendAdd to strength logA

Add exercises to a session WITHOUT touching what is already logged (agent write).

This tool cannot delete anything you did not send. Your exercises are appended to the day's existing session; an exercise whose name matches an existing one gets its sets appended to it. This is the right tool for "log the set I forgot" or for logging a session in installments while the owner is still in the gym — which is how strength data actually arrives.

Reach for log_strength_entry ONLY when you intend the supplied exercises to become the day's ENTIRE session and everything else to be deleted.

date is the LOCAL calendar day the session happened, "YYYY-MM-DD". exercises is [{"name": "卧推", "sets": [{"weightKg": 30, "reps": 8}, ...]}, ...].

This tool deliberately cannot set the session note: that field is replace-only, and a tool that promises to delete nothing must not carry an exception. Use log_strength_entry to change it.

The result is the same shape log_strength_entry returns. replaced_exercises is always [] here — that empty list is the receipt that this call deleted nothing. Encrypted end-to-end before it ever leaves this machine. Requires a bind made after the agent write path shipped; an older bind must re-pair by running uvx vaultbeat-apple-health@latest bind in a terminal.

Inputs: date (required), exercises (required). Returns: object

log_strength_entryLog strength session (replaces day)A
Destructive

Log one strength-training session on the owner's behalf (agent write).

⚠️ THIS TOOL DELETES. The supplied exercises become the day's ENTIRE session — any exercise you don't re-send is silently deleted. If you meant to ADD to a day rather than replace it, STOP and call log_strength_append instead; it cannot delete anything.

(merge=True still does the same thing as log_strength_append and keeps working for callers that already use it. New callers should use the separate tool: which one you called is visible to the owner, a flag buried in the arguments is not.)

The result carries replaced_exercises — the names this call deleted. If that list is non-empty and you did not intend to replace the day, you just destroyed those exercises; re-send them with merge=True.

note=None LEAVES THE EXISTING NOTE ALONE (pass note="" to clear it).

date is the LOCAL calendar day the session happened, "YYYY-MM-DD". exercises is [{"name": "卧推", "sets": [{"weightKg": 30, "reps": 8}, ...]}, ...]. Encrypted end-to-end before it ever leaves this machine — this server never sends plaintext. Requires a bind made after this feature shipped (carries owner_user_id/owner_public_key_base64/owner_device_id from the pairing handshake); an older bind must re-pair by running uvx vaultbeat-apple-health@latest bind in a terminal.

Inputs: date (required), exercises (required), note, merge. Returns: object

log_symptomLog symptomA

Record one symptom the person reports — one call per symptom (agent write).

This is where "我肚子疼" / "headache since lunch" / "拉肚子了" goes, not a note: each episode is kept as fields (type, severity, timing, place, suspected causes) so a later read can line it up with sleep, food, heart rate and wrist temperature. Two symptoms at once are two calls. This tool only ever adds; it cannot change or delete anything already recorded.

symptom_type: a short English token. Use the Apple Health name when one fits — abdominal_cramps, bloating, constipation, diarrhea, heartburn, nausea, vomiting, headache, dizziness, fatigue, fever, chills, coughing, sore_throat, runny_nose, lower_back_pain, chest_tightness_or_pain, shortness_of_breath, acne, night_sweats… — so it merges with what Apple Health imports; otherwise a plain descriptive one (rectal_bleeding, stomach_spasm, eye_strain). Any spelling is folded to one form. display_name: the person's own words, e.g. "便血" / "胃痉挛".

severity: mild | moderate | severe | unspecified. Use unspecified unless they said how bad it is — never grade it for them.

onset_at: when it began, ISO 8601 with their UTC offset, e.g. "2026-09-30T10:49+08:00". Omit it only for something happening NOW (it defaults to the current time). If they named a day but no time ("昨天头疼"), pass that day as a bare "2026-09-29" — do not invent an hour. end_at: when it eased, if they said; add it later with update_symptom. date: the local day to file it under, only when it differs from the onset's own day. body_location, note: free text, only what they said. triggers: what THEY suspect caused it, as short tokens (["bbq_dinner", "spicy_food"], ["sleep_deprivation"]). Record their suspicion; do not add causes of your own.

Returns entry_id (keep it for update_symptom / delete_symptom) and the entry as read back. Read everything with get_symptoms. Sealed for the owner and this machine only, end to end, before it leaves here.

Inputs: symptom_type (required), date, note, end_at, +5 more. Returns: object

log_weight_entryLog weight (replaces day)A
Destructive

Log the owner's weight (kg) on their behalf (agent write, 2026-07-21).

weight_kg: kilograms (positive, ≤500). date: LOCAL calendar day "YYYY-MM-DD" (default = today). Same-day upsert-in-place semantics (dayID = "body-{dayStart.epoch}") — re-logging the same day overwrites. Encrypted end-to-end before it ever leaves this machine.

A weight's home is Apple Health: the phone carries this one there on its next sync, through the iOS setting "Allow AI to update Apple Health" (MCP tab; OFF by default). It is also readable here at once (get_metric series "weight_kg").

⚠️ When no iPhone of this account has that setting on (with Weight access granted), the write is REFUSED and nothing is saved — from app 1.3.0 a weight may not live only in the cloud. The error says what to turn on; pass it on and do not retry until the person has done it. Never tell them to re-enter the number by hand in the Vaultbeat weight card instead: logging it in both places makes two entries for one day from different sources and corrupts the trend line.

Inputs: weight_kg (required), date. Returns: object

update_symptomUpdate symptom (overwrites given fields)A
Destructive

Change fields of one reported symptom (agent write) — e.g. it eased.

The common call is update_symptom(entry_id, end_at="…") when the person says it has stopped, or a new severity when it got worse. Only the fields you pass change; omitted ones keep their value. Passing a field OVERWRITES it: note replaces the old note rather than adding to it, and triggers replaces the whole list — read the entry first and send the combined list if you mean to add one. "" clears a text field or a mistaken end_at; [] clears triggers.

entry_id comes from log_symptom or from get_symptoms' reported list. Symptoms imported from Apple Health cannot be edited here.

Returns previous — the old value of every field this call changed — and the entry as read back.

Inputs: entry_id (required), date, note, end_at, +6 more. Returns: object

vaultbeat_doctorRun diagnosticsA
Read-onlyIdempotent

Diagnose this Vaultbeat MCP install, and report which data types are unavailable.

Call this when a read tool returns nothing, or when anything fails, before telling the user their data is missing. Two distinct things come back:

checks — the install/binding chain: config present, keypair usable, binding valid, cloud reachable, a real record decryptable end to end. A failure here means the setup is broken, not that data is absent.

capabilities — which metric kinds actually have data, and which empty ones are explained by an older iOS app (with the release date each needs). An empty kind is NOT proof the user never recorded it: their app may predate the feature entirely. A kind under kinds_not_checked could not be counted this run; it is neither empty nor full.

scope — what this report does NOT cover. Everything here can pass and the setup still be broken on the client side: this server is a subprocess of your MCP client, so it cannot read the client's config file, cannot see which environment variables the client forwarded, and cannot tell whether it was launched with the arguments the user believes. A green report never clears the client. scope.env_overrides_received lists which Vaultbeat variables actually arrived — check that before guessing at the client's environment.

binding — the local pairing state (which account, which server, whether demo mode is serving synthetic data). No keys or tokens.

This runs a cloud round trip, so it takes a moment.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target a distinct resource+action, and the descriptions include explicit 'which tool to use' guidance (e.g. get_sleep_detail vs get_sleep_nights vs get_metric, or get_metric vs get_intraday). However, the deliberate log_X_entry (replace) vs log_X_append (add) pairs, plus the many read tools over overlapping metric data, create genuine adjacency that an agent could misselect without reading the long caveats.

    Naming Consistency5/5

    Names follow a strict verb_noun snake_case convention throughout: get_*, log_*, update_*, delete_*, list_*, compare_*, correlate_*. The replace/append split is expressed consistently across note, strength, and food domains, with vaultbeat_doctor as the only (understandable) outlier.

    Tool Count3/5

    29 tools is heavy and sits at the edge of the 'too many' band for a single server. The health domain is broad enough that each tool is justified (multiple data types, read/append/replace variants), but the surface is large enough that an agent must navigate a lot of near-adjacent options.

    Completeness4/5

    Broad lifecycle coverage: symptoms, state of mind, notes, strength, food, weight, and metrics all have create/read (+update or append/delete) paths, and Apple-Health-sourced kinds are correctly read-only. Gaps are minor — no delete for food/strength/notes (only replace/append) — and are largely explained as intentional given the app as source of truth.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to read-only access Apple Health data through three tools: current status and sleep, detailed metrics, and 7/14/30-day trends, deployed via one-click on Cloudflare with private-key authentication.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to read Apple Health data through three tools: current stats, detailed metrics, and trends. Deployable to Cloudflare with a one-click phone setup, exposing only read-only access.
      MIT