Already use Tailscale?
Use the documented Tailscale Serve route when both the receiver and iPhone are already in the same tailnet. Tailscale is optional, not a product requirement.
Start with the App Store. Then connect your iPhone to a Mac or Linux computer that stores your health history and runs your AI client.
Receiver setup uses a terminal and a private network route. You'll need a computer that can stay awake and connected—not just the iPhone app.
Download the iPhone app from the App Store. TestFlight remains available for beta builds and prerelease testing.
The steps below use Direct sync. The receiver URL is not supplied by Apple Health AI Bridge: it is the private HTTPS route your iPhone uses to reach the receiver computer, including when the phone is away from home.
Prepare your route with the release-matched setup guide before running the commands below. It lists the prerequisites, including uv, which the receiver installation uses.
Use the documented Tailscale Serve route when both the receiver and iPhone are already in the same tailnet. Tailscale is optional, not a product requirement.
Use the setup guide's agent-assisted path. The setup agent must inspect first, preview every DNS, tunnel, proxy, firewall, and service change, and wait for approval.
Not a continuous-sync default: A local-network-only route stops syncing when the iPhone leaves that network. Do not copy a sample hostname or expose receiver port 8765 directly to the public internet.
Optional on Mac: Encrypted iCloud Mailbox (Beta) sends encrypted sync files through your own iCloud account. Direct remains the default, and Apple Health AI Bridge never switches between the two methods automatically. Linux receivers use Direct.
If you choose Mailbox, follow the Mailbox setup and verification guide instead of the Direct steps below. It covers the matching signed helper, service setup, and delivery checks. Once your first sync succeeds, continue with connecting your AI.
BASE="https://github.com"
OWNER="roian6"
REPO="apple-health-ai-bridge"
TAG="@receiver-v1.1.3"
URL="git+$BASE/$OWNER/"
URL="${URL}${REPO}.git${TAG}"
uv tool install "$URL"
# Routes A/B: run only after
# the guide sets the HTTPS URL.
health-bridge setup \
--receiver-url \
"$HEALTH_BRIDGE_RECEIVER_URL"
This installs Receiver/CLI 1.1.3, compatible with iPhone Companion 1.1.1 (50) and Batch Protocol 1.0.0.
The receiver can remain running while your AI reads synced data through the CLI or MCP.
For the deliberate Route C local-network-only fallback, use the real LAN URL and its required non-loopback bind instead:
health-bridge setup \
--receiver-url \
"$HEALTH_BRIDGE_RECEIVER_URL" \
--receiver-host 0.0.0.0 \
--receiver-port 8765
The version-pinned route guide explains how to configure the real URL for each route. Core setup creates the private receiver database and single-use pairing page, emits a same-host stdio MCP descriptor, and verifies the local MCP process. It does not prove receiver readiness or iPhone reachability. Setup does not modify client configuration unless you explicitly choose a client.
{"status":"ok"} from the printed local /health URL on the receiver host./health URL on the physical iPhone and require the same response. Routes A and B use HTTPS; Route C uses HTTP only on the same trusted LAN.Health access stays read-only, and you can change Apple Health permissions at any time in iOS Settings.
Syncing records does not automatically connect an assistant. Choose a client that supports local stdio MCP on the receiver computer, then use the AI connection guide to add it and check which records it can read.
For the exact command and arguments for this release, follow Connect an MCP client. You can add a client to an existing receiver without pairing your phone again.
Local configuration recipes. Reload your client and check its connection before asking it to use your records.
Run the client on the same Mac or Linux computer as your receiver and existing database. Local stdio is not a remote receiver URL. For a safe first check, you can use an existing synthetic-only receiver database instead of personal records.
In every example, replace /ABS/PATH/health-bridge with your installed executable's absolute path and /ABS/PATH/health.sqlite3 with the absolute path of your existing receiver database. Use the command and database path from setup's MCP descriptor; command -v health-bridge can also locate the executable. Do not use a relative path, ~, a receiver URL, or the placeholder itself.
Select and copy the code in your client's recipe, then replace both paths in your editor. Keep the quotes; escape any literal quote or backslash according to the shown JSON, TOML or YAML format. Each argument stays a separate value, including paths with spaces. Back up the client file and merge only the named health-bridge entry into its existing container. Do not overwrite the file or a different existing entry. These examples run the released health-bridge mcp start --db ABS_DB interface.
.agents/mcp_config.json, or global ~/.gemini/config/mcp_config.json for all workspaces. Choose one scope.mcpServers entry, replacing both absolute paths:
{
"mcpServers": {
"health-bridge": {
"command":
"/ABS/PATH/health-bridge",
"args": [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
}
}
}
health-bridge tools are available. Then try the first question..mcp.json in your project root. This recipe uses project scope, not Claude Desktop settings.mcpServers entry, replacing both absolute paths. Keep this private configuration out of shared source control:
{
"mcpServers": {
"health-bridge": {
"type": "stdio",
"command":
"/ABS/PATH/health-bridge",
"args": [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
}
}
}
/mcp. Once connected, try the first question.~/Library/Application Support/Claude/claude_desktop_config.json. This is the desktop app, not Claude web/mobile; native Windows receiver setup is outside this recipe.mcpServers entry, replacing both absolute paths:
{
"mcpServers": {
"health-bridge": {
"command":
"/ABS/PATH/health-bridge",
"args": [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
}
}
}
Full Claude Desktop walkthrough and troubleshooting · Official local-server tutorial
~/.codex/config.toml for your Codex CLI user configuration.mcp_servers.health-bridge does not already exist; otherwise review that entry. Replace both absolute paths:
[mcp_servers.health-bridge]
command = "/ABS/PATH/health-bridge"
args = [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
/mcp for health-bridge. Then try the first question..cursor/mcp.json, or global ~/.cursor/mcp.json for all projects. Choose one scope.mcpServers entry, replacing both absolute paths:
{
"mcpServers": {
"health-bridge": {
"type": "stdio",
"command":
"/ABS/PATH/health-bridge",
"args": [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
}
}
}
~/.hermes/config.yaml for the default Hermes profile. If you use another profile, edit its own config.yaml instead.mcp_servers mapping. Preserve YAML indentation and replace both absolute paths:
mcp_servers:
health-bridge:
command:
"/ABS/PATH/health-bridge"
args:
- "mcp"
- "start"
- "--db"
- "/ABS/PATH/health.sqlite3"
hermes mcp test health-bridge before the first question.Full Hermes walkthrough and troubleshooting · Hermes MCP documentation
~/.openclaw/openclaw.json, or the explicit configuration file your gateway uses. This recipe targets OpenClaw-managed MCP, not every ACP harness.health-bridge entry into mcp.servers. This is a strict JSON subset example, not an arbitrary JSON5 rewrite: retain unrelated settings, comments and syntax in your original file. Replace both absolute paths:
{
"mcp": {
"servers": {
"health-bridge": {
"command":
"/ABS/PATH/health-bridge",
"args": [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
}
}
}
}
openclaw mcp doctor health-bridge --probe to check the saved server. A config listing alone is not a connection test. Then try the first question.OpenClaw configuration reference · Connection and probe documentation
opencode.json, or user ~/.config/opencode/opencode.json. Choose one scope.mcp entry, replacing both absolute paths. OpenCode uses a single command array, not separate command and args fields:
{
"mcp": {
"health-bridge": {
"type": "local",
"command": [
"/ABS/PATH/health-bridge",
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
],
"enabled": true
}
}
}
opencode mcp list. Then try the first question, asking it to use health-bridge..vscode/mcp.json in local desktop VS Code. For user scope, run MCP: Open User Configuration from the Command Palette and choose Local if asked for a destination. Do not select an SSH, container or remote host.servers wrapper is not the portable Copilot mcpServers format; this recipe does not configure all Copilot harnesses:
{
"servers": {
"health-bridge": {
"type": "stdio",
"command":
"/ABS/PATH/health-bridge",
"args": [
"mcp", "start", "--db",
"/ABS/PATH/health.sqlite3"
]
}
}
}
health-bridge. Review the server trust dialog and tool permissions, then try the first question.Start with a synthetic-only database if you do not want to share personal records yet. Ask: “Use health-bridge to list the synced metric types and available date ranges. If there are no records, say so. Do not invent values.” An empty database is a valid first check, not evidence of a failed sync.
If tools are missing, check the selected client scope, both absolute paths, executable access and the client's server logs. Restart after correcting the file. Do not re-pair your phone just to reconnect a client. Configuration alone does not prove tool discovery or an AI answer.
Once connected, try: “How has my sleep changed since last week? Show the dates you used and any gaps.” Check the available dates before drawing conclusions; missing records are not zero values.
Your records are stored on your computer, but a cloud model provider may receive the query results your client sends. Review where your data goes before granting access.
For the available query operations and their limits, see the query interface reference for this release. Your client can also list the tools exposed by its connected server.
Contributors and advanced users can follow the versioned self-build guide.
Need a hand? Ask in our Discord community, or visit Support for other ways to get help.