How do I connect Apple Health to Claude Code?

What do you get?

Claude Code can read the Apple Health data you select through Syncky's local stdio MCP server and request permitted write-back with source and undo. Free during launch; plans are coming later. See launch access and pricing.

Relay sees delivery metadata and plaintext hub notices, but no health values: client health-data envelopes are sealed until the agent decrypts them. The local agent keeps plaintext JSON in its inbox; a chosen model sees what the agent supplies. The MCP server itself does not call an AI service. iOS schedules background sync and Health reads need an unlocked iPhone, so data can be hours old. Writes wait for sync; undelivered envelopes leave Relay on acknowledgment or expiry, at most 7 days.

What do you need before setup?

You need Syncky Health on your iPhone, Claude Code, Node.js 22.15 or newer and npm, outbound HTTPS to the matching relay and a private folder on your computer. Choose which data to share and which client/model may receive it. Use the agent setup guide to select the relay for your app build. Reuse an initialized home; initialize only a fresh home.

How do you set up Claude Code?

Check the runtime and local agent before pairing:
```
npx -y @syncky/agent selftest
```
For a fresh home only, initialize it with your chosen name:
```
npx -y @syncky/agent init --name "My agent"
```
Setup, receiver and MCP must use the same home and saved relay. The default home is ~/.syncky-agent. For a custom home, set SYNCKY_AGENT_HOME consistently before setup.
Create the private QR and code:
```
npx -y @syncky/agent pair
```
Scan in Syncky Health, pick the displayed code on the iPhone and select read types, allowed write types and Health permissions. Scanning alone does not confirm trust. Keep pairing credentials out of chat and logs. If a receiver is already running, let it receive the phone's proof; otherwise wait for it after the code pick:
```
npx -y @syncky/agent wait --timeout 600
```
Choose when to receive updates. For ongoing receiving, deliberately start this command, reusing an existing receiver if present:
```
npx -y @syncky/agent receive
```
Keep one receiver per home. For on-demand use, run npx -y @syncky/agent receive --once when you want updates. MCP neither pairs nor starts a receiver, and registration does not install a service.
Register the local MCP server:
```
claude mcp add --transport stdio syncky -- npx -y @syncky/agent mcp
```
For a custom home, substitute the actual paired home in this shell form:
```
claude mcp add --transport stdio syncky -e SYNCKY_AGENT_HOME="$HOME/.syncky-agent" -- npx -y @syncky/agent mcp
```
Alternatively, use the repository's MCP/skill plugin by entering these commands inside Claude Code:
```
/plugin marketplace add syncky/syncky-open
/plugin install syncky@syncky
```
For the carried plugin/skill, verify syncky-agent-claude-code.tar.gz against the matching release's SHA256SUMS, then run from the download directory:
```
tar -xzf syncky-agent-claude-code.tar.gz &&
claude plugin install syncky --marketplace "$PWD/claude-code"
```
Keep the complete package, including bundle, launcher and notices. Its carried launcher and MCP registration work without npm at runtime.

The public installation guide owns these recipes. A separate alternative for a compatible client is the matching release's checksum-verified syncky-health.mcpb; download its .sha256 sidecar and SHA256SUMS and verify before importing. Node.js is still required. A checksum detects damage, not a compromised release; local packaging tests do not prove client acceptance.
Run the scope-only prompt below before reading selected data.

What can Claude Code read and write?

The MCP server offers five tools. syncky_status shows pairing, scope and relay progress from local state. syncky_inbox returns what the iPhone sent, as raw JSON kept 30 days on your computer. syncky_skill returns the signed instructions that describe every message format. syncky_send sends a message to the iPhone: a Health write, applied at the next sync when the owner has allowed writing for that type and iOS Health permits it, or a sync report or access request, which the owner approves on the phone. syncky_ack marks inbox entries as handled. Status, inbox and skill only read; send and ack change things. An empty result is not a measured zero. This registration does not disable syncky_send or syncky_ack: keep tool approval on and never auto-allow them.

The agent keeps what the iPhone sent as daily JSON files in its home (inbox/), prunes them after 30 days, and keeps the last 100 send receipts. There is no database and no built-in summaries: your AI agent reads the files it needs.

Every write to Apple Health, every sync report request and every request for more Health types is a message the agent sends to the iPhone. Writes apply only to the types the owner allowed for writing in the app; a sync report or more Health types need the owner's tap on the phone. The signed skill (syncky_skill) carries the exact formats and limits. A report arrives only after you Review and Confirm on the iPhone; you can decline instead.

Write only owner-requested entries or entries covered by explicit standing approval. A write is applied only when its type is in the app's write allowance, within the agent's write scope, and authorized by HealthKit (iOS write permission). Each written entry identifies the requesting agent as its source. A queued or sent write is not an applied write: read the phone's result in the inbox after the next sync. To undo, use the iPhone's remove-written-entries control or have the agent send a delete command for its own entry. Follow the operator security rules.

How do you test the connection?

Ask Claude Code: Use syncky_status to check the paired iPhone and its read/write scope. Do not read sample values or write anything. Expect a confirmed iPhone and its last reported sharing/write scope. This reads local state without contacting Relay; it does not prove a fresh delivery or complete data.

How do you troubleshoot this setup?

Runtime or startup failure: make Node.js 22.15 or newer and npm available to the process starting MCP; run the selftest from setup.
Wrong or empty home: compare the receiver's home and saved relay with the MCP registration, including the custom-home environment.
Unconfirmed phone: pick the displayed code on the iPhone and let the existing receiver collect its proof, or run npx -y @syncky/agent wait --timeout 600 when no receiver is running. Do not reinitialize the home.
Stale or missing data: check that the receiver is running, the iPhone is unlocked, selected categories have Health read access and the app has synced. iOS controls background timing.
Pending write: read the phone's result in the inbox after the next sync; do not repeat a queued request to make it arrive sooner.

What are the frequently asked questions?

Does the plugin start continuous receiving?

No. The plugin registers MCP and supplies a skill. Use one separately chosen receiver on the same home. Services and schedules require an explicit request.

Can I use a carried skill without npm at runtime?

The matching release also carries a Claude Code skill archive with a checksum-checking launcher and bundle for offline use; see the public distribution guide. Relay operations need a reachable relay.

Where does the data go and when does it arrive?

The agent decrypts selected data and keeps it in its inbox for 30 days; your model sees what the agent supplies. iOS and the unlocked phone govern delivery, so a successful status check does not establish freshness. Review Privacy and the public security policy.

Agent setup · MCP comparison · All guides · FAQ.

How can an agent ask for more Health access?

Only with your explicit approval: the agent sends an access request with syncky_send, naming the read and write types it needs and an optional plain-text reason. A queued request grants nothing. The owner reviews each type on the phone and taps Allow or Decline; the reply arrives in the inbox and the next ordinary sync confirms the new scope. Asking for access is separate from permission to write Health values. The phone keeps one pending request per agent, admits one per rolling 24 hours, lets a request expire after 24 hours and waits seven days before a declined type can be asked again.