Metadata-Version: 2.4
Name: vaultbeat-mcp
Version: 0.5.1
Summary: Local MCP server for Vaultbeat — AI Health Sync: your AI agent reads your end-to-end-encrypted Apple Health data (sleep, cycle, weight, water), decrypted only on your machine
Project-URL: Homepage, https://vaultbeat.app
Project-URL: Repository, https://github.com/Fino-wind/vaultbeat-mcp
Project-URL: Issues, https://github.com/Fino-wind/vaultbeat-community/issues
Project-URL: Documentation, https://vaultbeat.app/mcp
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<50.0.0,>=48.0.1
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: keyring>=24
Requires-Dist: mcp<2.0.0,>=1.28.1
Requires-Dist: qrcode<9.0.0,>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.11.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.13.0; extra == "dev"
Requires-Dist: uvicorn>=0.30.0; extra == "dev"
Provides-Extra: qr
Dynamic: license-file

# Vaultbeat MCP Server

**Let your own AI agent read your health data — without the cloud ever seeing it.**

> ⚠️ **Skip the `pip install vaultbeat-mcp` box PyPI puts at the top of this
> page.** Every PyPI package page gets one automatically — it isn't a
> recommendation. Use `uvx` from Quick Start below: no separate install step,
> and with `@latest` it always runs the current release. A bare `pip
> install` (or a bare `uvx` without `@latest`) gets pinned to whatever was
> current the moment you ran it and will not update itself.

This is the official local [MCP](https://modelcontextprotocol.io) server for [Vaultbeat — AI Health Sync](https://apps.apple.com/app/id6759241985) (formerly named *Tether*), the iOS app that syncs Apple Health data (sleep, heart rate, menstrual cycle, weight, water, symptoms) between partners and to your own AI — end-to-end encrypted.

Vaultbeat embeds no AI and runs no model on your phone. Intelligence lives where you control it: Claude Code, Claude Desktop, or any MCP-capable agent running on your own machine. This server is the bridge — it holds a private key that never leaves your computer, pulls ciphertext from the cloud, and decrypts **only locally**.

```
iPhone (Apple Health) ──E2EE──▶ cloud (ciphertext only) ──E2EE──▶ this server (your machine) ──▶ your AI agent
```

## Requirements

- [Vaultbeat — AI Health Sync](https://apps.apple.com/app/id6759241985) on iOS, **version 1.2.3 or later** — 1.2.3 opened AI-server connections to every account; older builds restricted them, so update the app before pairing.
- Python 3.11+ on the machine where your agent runs (macOS / Linux / Windows)

## Quick start

### 1. Install

With [uv](https://docs.astral.sh/uv/) (recommended — no clone needed):

```bash
uvx vaultbeat-mcp@latest status
```

The `@latest` matters: without it, `uvx` only fetches the newest version the
*first* time you run the tool on a machine, then reuses its local cache on
every run after that — same as `pip`, which never updates once installed.
Keep `@latest` on every command below.

Or with pip (installs once, at whatever version is current right now — run
`pip install --upgrade vaultbeat-mcp` yourself to pick up new releases):

```bash
pip install 'vaultbeat-mcp[qr]'
```

> Upgrading from the old `tether-mcp` package? Same code, new name — your existing binding and config carry over unchanged. Just swap the package name in your install command and MCP client config.

### Try it first — no app, no pairing, no key

```bash
uvx vaultbeat-mcp@latest --demo doctor
uvx vaultbeat-mcp@latest --demo sleep --limit 5
uvx vaultbeat-mcp@latest --demo serve --transport stdio   # same dataset, wired into your agent
```

`--demo` is a **global flag**: it goes *before* the subcommand, and `VAULTBEAT_DEMO=1` does the
same thing. It serves a deterministic synthetic dataset covering every data type this server can
read — the same records on every machine and every run, so demo output can be pasted into a bug
report as a shared baseline. Nothing is fetched, nothing is decrypted, and there is no private
key involved at all, so you can see exactly what your agent would be able to answer before
installing anything on your phone.

Demo output is built so it cannot be mistaken for a real export: every MCP tool result carries
`demo_mode: true` and a `[SYNTHETIC DEMO DATA]` banner, each tool's description says so, and the
server introduces itself to your client as `Vaultbeat Health [DEMO — SYNTHETIC DATA]`. The
`log_*` write tools deliberately **refuse** in demo mode — 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.
The flag applies to that one invocation only and is never written to your config.

⚠️ **Synthetic numbers are not health observations.** They are generated locally and belong to
no real person — don't save them into a note or file, and don't let an agent reason about anyone's
health from them.

### 2. Bind your phone

```bash
uvx vaultbeat-mcp@latest bind
```

`bind` is the command that draws the QR code, and it waits while you scan.
`serve` (step 3) prints nothing at all — it is the stdio protocol loop — so
don't start that one first and sit waiting for a code.

(The `[qr]` extra was required until 0.3.10, which made `qrcode` a hard
dependency. The extra is still declared, empty, so older published commands
keep resolving; you no longer need it.)

This generates a keypair on your machine and prints a QR code. In the Vaultbeat iOS app, open **Settings → Data & AI → Connect an AI server** and scan it (or import a QR screenshot from Photos). The app authorizes this machine and starts sealing your health envelopes to its public key. Config lives in `~/.tether/mcp-local/` with owner-only `0600` permissions. (The directory keeps its original pre-rename path so existing bindings survive upgrades.)

**Where the private key is kept — it is never uploaded anywhere, but *where* it sits depends on the machine:**

| Layer | When it is used |
|---|---|
| `VAULTBEAT_PRIVATE_KEY` environment variable | If set, it wins. Read only — never written back, because an injected key belongs to whoever injected it |
| System keyring | The default on any machine that has one (macOS Keychain, GNOME Keyring, Windows Credential Locker) |
| `identity.key`, `0600`, next to `config.json` | **Only** when the platform has no keyring backend at all — a headless server, a container |

The file fallback is deliberately narrow: a *locked* keychain, a denied prompt, or a D-Bus hiccup all raise instead of quietly writing a plaintext key to disk. It is a separate file from `config.json` on purpose — that file holds your server token, and `config.json` is what people `cat` into bug reports. The token alone can download ciphertext it cannot read; the key alone has nothing to decrypt. Keeping them apart means one careless paste is not total exposure.

Run `uvx vaultbeat-mcp@latest doctor` to see which of the three your machine is actually using (it reports the *layer*, never the key).

> **Headless Linux**: if the keyring errors out even though a desktop session exists, the usual cause is that the process was launched without `DBUS_SESSION_BUS_ADDRESS` and `XDG_RUNTIME_DIR`. Add both to the MCP server's launch environment. On a truly headless box with no keyring at all, do nothing — the `identity.key` fallback handles it. Never set `PYTHON_KEYRING_BACKEND` to the null backend to silence the warning: it accepts writes and stores nothing.

### 3. Connect your agent

**Claude Code** (one line):

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

**Claude Desktop** (`claude_desktop_config.json`):

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

Any other MCP client: run `uvx vaultbeat-mcp@latest serve --transport stdio`, or `--transport http` for a loopback streamable-HTTP endpoint with bearer-token auth.

> **Claude Desktop note**: it does not inherit your shell `PATH`. If `uvx` isn't found, use the absolute path (`which uvx`) as `command`.

Debugging: `npx @modelcontextprotocol/inspector uvx vaultbeat-mcp@latest serve --transport stdio`

Then just ask your agent: *“How did we sleep last night?”*

<!-- Keep this count in step with the table below: 19 read + 7 write + 2 bind + doctor = 29.
     The get_hrv_hourly row is a granularity argument to get_hrv, not a registered tool, so the
     table always has one more row than the heading counts.
     This said (16) until 2026-07-31 while the table already listed all 26 — directory listings
     render the heading, not the table, so the stale number was the public-facing one.
     0.5.0 took write from 4 to 7 by splitting the `_append` tools out of the `merge=True` flag.
     Source of truth is the code, not this comment: `grep -cE '^    @tool' mcp_server.py`. -->
## MCP tools (29)

| Tool | Returns |
|---|---|
| `vaultbeat_status` | Local binding state (never exposes keys or tokens) |
| `vaultbeat_doctor` | Full self-diagnosis: install/binding chain **plus** which data types have data and which need a newer iOS build — call this before concluding data is missing |
| `vaultbeat_start_binding` | A fresh QR binding payload for the iOS app to scan |
| `vaultbeat_poll_binding` | One poll for the iOS authorization to complete binding |
| `vaultbeat_sync_sleep` | Recent sleep sessions incl. heart-rate samples, per-day primary-session selection matching the iOS app |
| `get_sleep_detail` | Per-night heart-rate + respiratory-rate + sleep-stage timeline |
| `get_water_intake` | Daily water intake + computed daily average |
| `get_weight_trend` | Daily weights + latest/avg/min/max + weekly trend rate, plus body composition (`body_fat_percent` 0–100, `bmi`, `lean_body_mass_kg`) when a smart scale wrote it into Apple Health |
| `get_menstrual_cycle` | Cycle samples + next-period prediction *(sensitive — explicit iOS opt-in required)* |
| `get_symptoms` | HealthKit symptom days grouped by data owner *(sensitive)* |
| `get_notes` | Free-text day annotations with their writer *(sensitive)* |
| `get_activity` | Daily activity rings: steps / energy / exercise minutes / stand hours / distance |
| `get_resting_hr` | Resting heart-rate records + window mean |
| `get_workouts` | Workout records: type / duration / calories / distance |
| `get_mindfulness` | Mindful sessions and minutes per day |
| `get_hrv` | Heart-rate variability (SDNN) records + window mean |
| `get_wrist_temp` | Sleeping wrist-temperature baseline deviation |
| `get_hrv_hourly` *(via `get_hrv(granularity="hourly")`)* | Hour-bucketed HRV averages over 30 days — the context-cheap default; `granularity="raw"` keeps minute-level spike precision |
| `get_vo2max` | VO₂ max records + latest / peak / trough / window average |
| `get_basal_energy` | Basal (resting) energy burned, per hour bucket |
| `get_total_energy_burned` | **TDEE** — basal + active per day, measured rather than estimated, with today flagged partial and excluded from the average |
| `get_strength_log` | Structured strength training: exercise, sets, reps, weight per day |
| `get_food_log` | Meals as free text with optional portions and timing |
| `log_weight_entry` | **Write** a weight entry (optionally mirrored into Apple Health when the user opts in). Carries over that day's existing body composition instead of erasing it — an agent cannot supply fat/BMI/lean mass, so a bare weight log must not wipe what the scale recorded |
| `log_strength_entry` | **Write** a strength session for a day — **replaces that whole day**. Use `log_strength_append` unless you mean to delete what is already there |
| `log_strength_append` | **Write** exercises onto a day *without deleting anything*; sets are appended to a matching exercise name. The tool for "log the set I forgot", or for logging a session in installments while the owner is still in the gym |
| `log_food_entry` | **Write** a day's meals — **replaces that whole day**. Use `log_food_append` unless you mean to delete what is already there |
| `log_food_append` | **Write** extra meals onto a day *without deleting anything* — the right tool whenever the day may not be empty |
| `log_note` | **Write** a mood or general note for a day — **replaces that day's note** |
| `log_note_append` | **Write** one more line onto a day's note *without erasing what is there*. Use this for symptoms: discomfort arrives in installments, so a second write the same day is the normal case |

> ⚠️ **`log_strength_entry` / `log_food_entry` / `log_note` replace the WHOLE DAY.** Passing only
> what you want to add deletes everything else recorded that day. Since 0.5.0 each one has an
> `_append` twin — `log_strength_append` / `log_food_append` / `log_note_append` — that only adds
> and *cannot* delete. **Prefer the `_append` form whenever the day may not be empty**, which an
> agent generally cannot tell without reading it back first. (The three replace-tools still accept
> `merge=True` for the same effect; the `_append` tools make the safe option reachable by name
> instead of by remembering a flag.) Every write returns a `replaced_*` field naming exactly what
> it deleted — from an `_append` call that field is always `[]` / `null`, which is the receipt
> that nothing was. `log_weight_entry` has no twin: a day has one weight.

Every data tool accepts `owner` (a user-ID prefix) to filter to one person — the server may hold both your and your partner's shared records, and omitting `owner` mixes them into one pool, so per-person questions should always pass it. (Earlier releases named some tools `get_partner_*` / `tether_*`; they were renamed in the 16-tool and Vaultbeat releases.)

Reads are cache-first: decrypted records are cached locally (owner-only files, 600 s TTL, `VAULTBEAT_MCP_CACHE_TTL` to override — the pre-rename `TETHER_MCP_*` spellings still work) so repeat queries answer in ~0.2 s with zero network; pass `fresh=true` to force a cloud round trip. The same service layer backs a full CLI (`uvx vaultbeat-mcp@latest sleep / water / weight / …` — every data subcommand takes `--owner` too) if you prefer scripts over MCP.

## Privacy & security model

- **End-to-end encryption**: Curve25519 ECDH + HKDF-SHA256 + AES-GCM. Every health record is sealed on-device to each authorized recipient's public key (your partner, and this server once bound).
- **The cloud only ever holds ciphertext.** Vaultbeat's backend cannot read your health data — architecturally, not just by policy.
- **Decryption happens here**, on hardware you own. The private key and server token are never exposed through any tool result.
- **Sensitive kinds** (menstrual cycle, symptoms, notes) reach this server only if explicitly opted in inside the iOS app, and are never re-exported by the server.
- HTTP transport binds to loopback by default and requires a bearer token; binding a non-loopback address fails closed unless explicitly allowed — front it with TLS if you must expose it.

You can audit all of the above in this repository — that is why it is open source.

## Development

```bash
pip install -e '.[dev,qr]'
pytest
```

## License

[MIT](LICENSE). The Vaultbeat iOS app and cloud service are separate proprietary components; this repository covers the local MCP server only.

---

*Website: [vaultbeat.app](https://vaultbeat.app) · App Store: [Vaultbeat — AI Health Sync](https://apps.apple.com/app/id6759241985) · Bugs & feedback: [vaultbeat-community](https://github.com/Fino-wind/vaultbeat-community/issues)*

<!-- mcp-name: io.github.Fino-wind/vaultbeat-apple-health -->
