Vaultbeat MCP Server

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 — connecting an AI server is open on every plan, and pairing a machine starts three days of full agent access. (On 1.2.2 and earlier, connecting required a Pro subscription; update the app first.)
• 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.

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 (26)

⚠️ The three log_* write tools replace the WHOLE DAY by default. Passing only what you want to add will delete everything else recorded for that day. Pass merge=True to append instead — that is almost always what you want when adding to a day that already has data. Every write returns a replaced_* field naming exactly what it deleted, so an agent can notice and re-send. Since 0.2.4; before that the deletion was silent and there was no merge mode.

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