Vaultbeat Local MCP Server

Your Apple Health data — sleep stages, cycle, HRV, resting heart rate, workouts, weight, VO₂ max, meals, lifts, notes — readable and writable by your own AI agent (Claude Code, Hermes, OpenClaw, anything MCP), end-to-end encrypted so that only your machine ever sees plaintext. The Vaultbeat iPhone app captures from HealthKit; this package is the local server that decrypts for the agent.

Technically: the local service program for Vaultbeat's encrypted health-data recipient flow. Published externally as Fino-wind/vaultbeat-apple-health (public package name vaultbeat-apple-health since 0.6.2; vaultbeat-mcp and vaultbeat-mcp-local remain back-compat console scripts). This directory is the source of truth — after any user-visible change here, re-export the public repo and update its README tool table + the website /mcp page (see CLAUDE.md "Sync duty").

It runs on the user's computer, generates the Curve25519 keypair used by the iOS app, shows a QR binding payload, receives a one-time server token from the cloud API, and then exposes decrypted health data — sleep, water, weight, cycle, activity, vitals — through either a CLI or a stdio MCP server. Read-only: data is written by the iOS app.

Commands

python -m pip install -e './mcp-local-server[qr]'
# try every read tool against synthetic data — no pairing, no cloud, no Apple Health
vaultbeat-apple-health --demo sleep --limit 5
vaultbeat-apple-health --demo doctor

vaultbeat-apple-health bind
vaultbeat-apple-health status

# read decrypted health data — every data subcommand accepts
# --owner <user-id prefix> to filter to one person (omitting it mixes
# both partners' records into one pool; aggregates become meaningless)
vaultbeat-apple-health sleep --limit 5 --owner a1a1        # sleep sessions + provenance
vaultbeat-apple-health sleep-detail --limit 1 --owner a1a1 # HR+RR+stage timeline
vaultbeat-apple-health water --limit 30 --owner a1a1       # water intake + daily average
vaultbeat-apple-health weight --limit 90 --owner b2b2      # weight trend (latest/avg/weekly rate)
vaultbeat-apple-health menstrual --limit 60 --owner b2b2   # menstrual cycle (sensitive)
vaultbeat-apple-health activity --limit 30 --owner a1a1    # daily activity rings
vaultbeat-apple-health resting-hr --limit 30 --owner a1a1  # resting heart rate
vaultbeat-apple-health workouts --limit 20 --owner a1a1    # workout records
vaultbeat-apple-health mindfulness --limit 30 --owner a1a1 # mindful minutes
vaultbeat-apple-health hrv --limit 30 --owner a1a1         # HRV / SDNN (hourly buckets by default; --granularity raw for per-sample)
vaultbeat-apple-health wrist-temp --limit 30 --owner a1a1  # sleeping wrist temperature
vaultbeat-apple-health symptoms --limit 30                 # symptom days (grouped by owner)
vaultbeat-apple-health notes --kind sleep --limit 30       # free-text day annotations

# run as an MCP server
vaultbeat-apple-health serve --transport stdio
vaultbeat-apple-health serve --transport http --host 127.0.0.1 --port 8000 --path /mcp
vaultbeat-apple-health --demo serve --transport stdio   # same synthetic dataset, wired into a client

--demo is a global flag, not a subcommand: it goes before the subcommand (vaultbeat-apple-health --demo sleep), and VAULTBEAT_DEMO=1 does the same thing. It serves a deterministic synthetic dataset — the same records on every machine, every run — so demo output can be pasted into a bug report as a shared baseline. Nothing is fetched and nothing is decrypted; there is no private key involved at all. Every payload carries demo_mode: true plus a [SYNTHETIC DEMO DATA] banner, the tool descriptions say so, and the server lists itself as Vaultbeat Health [DEMO — SYNTHETIC DATA], so demo output cannot pass for a real export. Read tools only — the log_* write tools refuse, because writing needs a real key and a real account, and a write that pretends to succeed is worse than one that says it needs pairing. It applies to that one invocation and is never written to the config file.

http is a CLI alias for MCP's streamable-http transport. The default transport remains stdio for local desktop MCP clients.

The config file defaults to ~/.tether/mcp-local/config.json and is written with 0600 permissions. It contains the cloud-issued server token and your public key; do not commit or share it.

Where the private key lives

Not in config.json. It is looked for in three places, in order:

1. VAULTBEAT_PRIVATE_KEY — read if set, never written back, for operators who inject it from systemd-creds / a vault / a KMS.
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 backend at all.

Keeping it out of config.json is a boundary, not tidiness: the server token alone can download your ciphertext but not read it, and the private key alone has nothing to decrypt. config.json is the file people cat into bug reports.

🔴 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 brand-new identity, and every record already encrypted for the old one becomes permanently unreadable. If a command reports missing key material, the error names all three locations and what was found in each; read that before removing anything.

Headless servers: if the keyring is unreachable, do not set PYTHON_KEYRING_BACKEND to the null backend. That backend accepts writes and stores nothing; since 0.4.3 every keyring write is verified by reading it back, so a null backend just lands the key in layer 3's identity.key file — the same outcome as having no keyring, with a keyring you might have reached hidden behind it. Either let layer 3 handle it (automatic when no backend exists) or, if a D-Bus session exists but this process cannot see it, pass DBUS_SESSION_BUS_ADDRESS through explicitly — XDG_RUNTIME_DIR on its own is not enough.

.tether, not .vaultbeat — that is deliberate, do not "fix" it. The app was renamed but this path is frozen at the pre-rename location, because the Keychain username embeds the resolved config path (_keychain_username in store.py). Moving the directory orphans the bound config and its private-key Keychain entry for every existing install. Until 2026-07-28 this README wrote ~/.vaultbeat/..., which does not exist — so anyone who came here to destroy their credentials rm -rf'd an empty path, got no error, and left the real key in place.

When using HTTP transport, the server binds to 127.0.0.1:8000 and serves MCP at /mcp by default, and requires a bearer token (see "Authenticating HTTP transport" below). Binding a non-loopback address fails closed unless you pass both a token and --allow-remote; always front a network-exposed server with TLS (a reverse proxy).

Binding Flow

1. vaultbeat-apple-health bind generates a fresh pollID and prints a QR payload: {"pollID":"...","publicKeyBase64":"...","serverName":"..."}
2. The iOS app scans that payload and calls the mcp-bind-local Edge Function.
3. The local service polls the mcp-poll-binding Edge Function.
4. Once bound, the local config stores serverID and serverToken.
5. All read commands call the mcp-sync Edge Function, decrypt the returned envelopes locally, and return plaintext JSON. (All privileged routes are Supabase Edge Functions at /functions/v1/<name>.)

Troubleshooting: vaultbeat-apple-health doctor

If binding or reads fail, run the self-diagnosis:

vaultbeat-apple-health doctor          # human-readable [OK]/[FAIL] checklist with hints
vaultbeat-apple-health doctor --json   # machine-readable, for agents

It checks, in order: config file → identity key (Keychain) → cloud reachability → binding state → a real fetch-and-decrypt round trip, and prints a targeted hint for the first thing that's broken (e.g. "codes expire after 10 minutes — re-run bind for a fresh QR", or "the stored key can no longer decrypt your data — delete this server in the iOS app and bind again"). Exit code 0 = all healthy, 1 = something needs the hint above.

MCP Tools (33)

vaultbeat-apple-health serve can start either a stdio MCP server or a streamable HTTP MCP server. Every data tool accepts owner (user-ID prefix) to filter to one person and fresh to bypass the local cache — omit owner and both partners' records mix into one pool, so per-person analysis must always pass it. The tool names dropped the old misleading get_partner_* prefix in the 16-tool release (2026-07-16): the tools return whichever owners' envelopes this server holds, not specifically "the partner".

Binding / status:

• vaultbeat_status — local binding state (no keys/tokens in the result)
• vaultbeat_start_binding — generate a fresh QR binding payload
• vaultbeat_poll_binding — poll once for the iOS authorization
• vaultbeat_doctor — diagnose this install end to end, and report which data types are unavailable and why. Call it before telling a user their data is missing.

Health data: