Vaultbeat MCP Server
Vaultbeat MCP Server gives an AI agent locally-decrypted read and write access to your Apple Health data — sleep, cycle, HRV, workouts, food, strength, moods, symptoms and notes — plus server-side analysis, with everything encrypted end-to-end so only your machine sees plaintext.
Diagnose the install:
vaultbeat_doctorchecks config, key, cloud reachability, pairing and a real decrypt round trip, and reports which data types are empty and why.Read sleep:
get_sleep_nights(one compact row per night, a year per call),get_sleep_detail(per-stage intervals and per-stage HR/breathing rate for one or two nights).Read sensitive records:
get_menstrual_cycle(with next-period prediction),get_symptoms(Apple Health days plus self-reported episodes),get_state_of_mind(moods/valence),get_notes(day annotations).Read logs and workouts:
get_strength_log(exercises, sets × reps, volume),get_food_log(meals, items, optional kcal/macros),get_workouts,get_user_profile(sex, age, DOB, height).Daily metrics:
get_metricfor any series — steps, resting HR, HRV, weight/body composition, VO₂ max, water, energy, sleep stages and timing — with server-side aggregation (avg/sum/min/max/latest) and day/week/month/weekday granularity.Intraday and series discovery:
get_intradayfor within-day HRV samples;list_metric_seriesto see every available series and how much data backs it.Analysis:
get_metric_trend(least-squares slope),compare_metric_periods(newest N vs prior N, or two named windows),correlate_metric_series(Pearson r, with optional lag) — numbers only, no verdicts, and refuses on too few points.Write data: append-only
log_food_append,log_strength_append,log_note_append,log_symptom,log_weight_entry; replace-whole-daylog_food_entry,log_strength_entry,log_note(all report exactly what was removed);log_state_of_mind.Correct writes:
update_symptom,delete_symptom,delete_state_of_mind.Partner reads: sleep, water, weight and (if the partner opts in) cycle, symptoms, moods and notes via
partner=true, kept strictly separate from your own data; notes about your partner stay in your account.Serves 8 MCP prompts (e.g.
daily_brief,sleep_review,energy_balance,why_is_this_empty) that name the tools to call and the coverage/empty-result rules.Run anywhere: stdio or HTTP transport with bearer-token auth, plus a
--demosynthetic dataset for trying it without an iPhone.Coverage-aware results: every read reports
coverage.days_covered,more_availableandoldest_available, so a limit-shaped window is never mistaken for the extent of your history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Vaultbeat MCP Server How did we sleep last night?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Vaultbeat Apple Health MCP Server
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 agentThe 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+, anduvxdownloads 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 bindIt 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@vaultbeatThen run /vaultbeat-apple-health:setup. Or add only the server:
claude mcp add vaultbeat-health -- uvx vaultbeat-apple-health@latest serve --transport stdioClaude 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 doctorIt 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 |
| 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 |
| 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; |
| One or two nights in depth: stage intervals with per-stage heart and breathing rate. The newest nights, or any night by date ( |
| Cycle samples and a next-period prediction. Sensitive. |
| Symptoms from Apple Health, and beside them the episodes a person reported (type, severity, onset and end, place, suspected triggers). Sensitive. |
| 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 |
| Free-text notes on days, with who wrote them. Sensitive. |
| Strength sessions: exercises, sets × reps, volume per session. |
| 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 |
| Workouts: type, duration, calories, distance. |
| Sex, age, date of birth and height. Needs Vaultbeat for iOS 1.2.9 or later. |
Daily numbers and analysis
Tool | What it returns |
| 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. |
| Samples within a day, for HRV: one row per hour that has samples ( |
| Every series name the tools above and below accept, with its unit and how much data backs it. |
| Least-squares slope, endpoints, mean / median / min / max. |
| The newest N days against the N before them, or two named windows. |
| Pearson r between two series over the days that have both; |
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 |
| Add to a day. Cannot delete anything — the safe default when a day may already have entries. |
| Replace that whole day with what is passed, and report exactly what was removed. |
| Record a weigh-in, keeping that day's body composition. |
| Record one symptom the person reports, as structured fields a later read can match against sleep, food and heart rate. |
| Change a reported symptom (usually its end time), or erase one logged by mistake. |
| 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). |
| 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
coverageblock.days_coveredis how many distinct days the answer rests on — quote it beside any average or trend.more_available: truemeans older records exist and yourlimitstopped short of them (oldest_availablesays 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_largewith a suggestion for narrowing the request (a smallerlimit, asincedate, one series instead of all).get_metricandget_intradayreturn 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 throughlog_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:
the
VAULTBEAT_PRIVATE_KEYenvironment variable, if set (read, never written back) — for operators injecting it from a secret store;the system keyring — the normal case on a desktop;
~/.tether/mcp-local/identity.key, mode0600— 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.jsonto "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, runbindagain: 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 requiredThe 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 srcvaultbeat-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 toolscompare_metric_periodsCompare two periodsARead-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 seriesARead-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)ADestructive
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)ADestructive
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 logARead-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 samplesARead-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 itssample_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 cycleARead-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 metricsARead-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 trendARead-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_notesNotesARead-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 detailARead-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 nightARead-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)ARead-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 logARead-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_symptomsSymptomsARead-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 profileARead-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_workoutsWorkoutsARead-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 seriesARead-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)ADestructive
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)ADestructive
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)ADestructive
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)ADestructive
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)ADestructive
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 diagnosticsARead-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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
Your Apple Health data, food diary and lifts, for ChatGPT, Claude and Gemini. Approved on iPhone.
Read-only Apple Health data synced from your iPhone: sleep, heart rate, HRV, workouts and trends.
Connect your health, fitness, nutrition, sleep, and wearable data to your AI assistant.
Your labs, wearables, DNA and notes as one health record your AI agent can read (OAuth 2.1).
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI to read-only access Apple Health data (current status, sleep, trends) via a Cloudflare-deployed MCP server, using iPhone shortcuts to sync data.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceProvides AI with read-only access to Apple Health data via three tools (health_now, health_detail, health_trends). Deployable on Cloudflare with a one-click mobile setup.1MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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