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 server for Vaultbeat — AI Health Sync (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 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 (recommended — no clone needed):

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):

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

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

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:

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):

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

Claude Desktop (claude_desktop_config.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?”

MCP tools (29)

⚠️ 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

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

License

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

Website: vaultbeat.app · App Store: Vaultbeat — AI Health Sync · Bugs & feedback: vaultbeat-community