Set up your bridge.

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.

Requires iOS 18 or later, a Mac or Linux receiver, and an MCP client on that computer.

1. Install the iPhone companion

Download the iPhone app from the App Store. TestFlight remains available for beta builds and prerelease testing.

2. Choose a route before setup

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.

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.

Agent-assisted private HTTPS ingress

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.

3. Install and run setup

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.

4. Supervise, verify, pair, and enable sync

  1. Put the command printed by setup under the host's approved service manager, then start the receiver.
  2. Require {"status":"ok"} from the printed local /health URL on the receiver host.
  3. Open the exact phone-facing /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.
  4. Open the private pairing page on the receiver computer and scan its QR with iPhone Camera.
  5. Connect the iPhone app and review Apple’s native permission sheet.
  6. Enable Automatic Sync and wait for the first successful receiver upload.

Health access stays read-only, and you can change Apple Health permissions at any time in iOS Settings.

5. Connect your AI and ask

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.

Before you add a client

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.

Antigravity CLI
  1. On the receiver computer, open workspace .agents/mcp_config.json, or global ~/.gemini/config/mcp_config.json for all workspaces. Choose one scope.
  2. Merge this mcpServers entry, replacing both absolute paths:
    {
      "mcpServers": {
        "health-bridge": {
          "command":
            "/ABS/PATH/health-bridge",
          "args": [
            "mcp", "start", "--db",
            "/ABS/PATH/health.sqlite3"
          ]
        }
      }
    }
  3. Restart the CLI session, review any server/tool trust request, and check that health-bridge tools are available. Then try the first question.

Antigravity MCP documentation

Claude Code
  1. On the receiver computer, open .mcp.json in your project root. This recipe uses project scope, not Claude Desktop settings.
  2. Merge this 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"
          ]
        }
      }
    }
  3. Restart Claude Code in that project, approve the project MCP server when asked, and inspect /mcp. Once connected, try the first question.

Claude Code MCP documentation

Claude Desktop
  1. On the receiver Mac, open Claude Desktop → Settings → Developer → Edit Config: ~/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.
  2. Merge this mcpServers entry, replacing both absolute paths:
    {
      "mcpServers": {
        "health-bridge": {
          "command":
            "/ABS/PATH/health-bridge",
          "args": [
            "mcp", "start", "--db",
            "/ABS/PATH/health.sqlite3"
          ]
        }
      }
    }
  3. Completely quit and restart Claude Desktop. Review tool permissions and the server's connection status before trying the first question.

Full Claude Desktop walkthrough and troubleshooting · Official local-server tutorial

Codex CLI
  1. On the receiver computer, open ~/.codex/config.toml for your Codex CLI user configuration.
  2. Add this table only if 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"
    ]
  3. Restart Codex CLI, review its MCP/tool approval settings, and inspect /mcp for health-bridge. Then try the first question.

Codex MCP documentation

Cursor
  1. On the receiver computer, open project .cursor/mcp.json, or global ~/.cursor/mcp.json for all projects. Choose one scope.
  2. Merge this mcpServers entry, replacing both absolute paths:
    {
      "mcpServers": {
        "health-bridge": {
          "type": "stdio",
          "command":
            "/ABS/PATH/health-bridge",
          "args": [
            "mcp", "start", "--db",
            "/ABS/PATH/health.sqlite3"
          ]
        }
      }
    }
  3. Restart Cursor and review the server in Cursor Settings → Tools & MCP. Enable it and review tool approvals before the first question. This is local editor setup, not cloud-agent access.

Cursor MCP documentation

Hermes Agent
  1. On the receiver computer, open ~/.hermes/config.yaml for the default Hermes profile. If you use another profile, edit its own config.yaml instead.
  2. Merge this server under the existing 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"
  3. Restart Hermes with the same profile so it discovers the tools. Review access and run hermes mcp test health-bridge before the first question.

Full Hermes walkthrough and troubleshooting · Hermes MCP documentation

OpenClaw
  1. On the receiver computer, open ~/.openclaw/openclaw.json, or the explicit configuration file your gateway uses. This recipe targets OpenClaw-managed MCP, not every ACP harness.
  2. Manually merge the 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"
            ]
          }
        }
      }
    }
  3. Restart the gateway with that configuration, review tool permissions, and use 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
  1. On the receiver computer, open project opencode.json, or user ~/.config/opencode/opencode.json. Choose one scope.
  2. Merge this 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
        }
      }
    }
  3. Restart OpenCode in the intended project, review tool permissions, and inspect opencode mcp list. Then try the first question, asking it to use health-bridge.

OpenCode MCP documentation

Visual Studio Code
  1. On the receiver computer, open workspace .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.
  2. Merge this VS Code Local servers format entry, replacing both absolute paths. The 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"
          ]
        }
      }
    }
  3. Use the config editor's Start action, or MCP: List Servers to restart health-bridge. Review the server trust dialog and tool permissions, then try the first question.

VS Code MCP setup · Local configuration reference

Check the connection, then ask

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.

Build from source

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.