Query Apple Health with Any AI Agent
By the end of this page every agent you use answers from your real Apple Health data: one zero-dependency server, installed once, no outbound network calls. Config blocks for Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, Codex CLI, opencode and OpenClaw, plus the queries that work in all of them.
AI-assisted, human reviewed. How we use AI
Quick answer: A single zero-dependency MCP server connects your Apple Health data to every major AI agent. Install the MetricBridge iOS app (read-only HealthKit access, writes JSON to your iCloud Drive), then add the same node server.mjs command to each client's config. The server exposes 21 tools, 19 of them read-only (add_event and remove_event write only health-events-agent.json beside the export). The read-only ones are: get_mcp_status, get_freshness, list_metrics, get_health_metrics, get_trends, compare_periods, get_structured_export, get_intraday, query_health_data, list_events, get_profile, get_workouts, get_sleep_sessions, get_cycle_context, correlate_metrics, and resolve_metric. The server makes no outbound network calls, so nothing reaches us or a cloud AI. Source on GitHub, npm package health-export-mcp (1.8.0), full tool list on the MCP page.
Over the last year, the MCP ecosystem went from a single reference implementation to a dozen Apple Health connectors, each with its own dependencies and setup story. If you use more than one AI agent, you have probably typed the same config into three different files by hand.
This guide eliminates that. One MCP server, installed once, wired into every client that speaks MCP. The server is a single server.mjs file with zero npm dependencies. It reads a local JSON file that your iPhone writes, and it never makes a network call. Every config block below is copy-paste ready.
Before you start: what you need
Two things, same for every client:
- MetricBridge on iOS. Install from the App Store, grant HealthKit read access, turn on export. Choose iCloud Drive as your destination (the OS syncs it to your Mac automatically).
- Node.js on the computer where your AI agents run. Any recent LTS works. The server is a plain
nodeinvocation: no global install, no Docker, no Python.
Two values you will paste everywhere. SERVER_PATH is the absolute path to server.mjs (e.g. /Users/you/.health-export-mcp/server.mjs or wherever you cloned the repo). HEALTH_DATA_DIR is the folder holding your .health-cache.json. If you use iCloud sync on macOS:
/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents
Expand ~ to your real home path. Most clients do not expand tildes.
The server: what tools does it expose?
Twenty-one tools, all local, 19 of them read-only. The table shows the ten you will call most; the MCP page lists all 18 and the 23 prompts.
| Tool | What it returns |
|---|---|
get_mcp_status | Health check: data source, metric count, most recent data date. Call this first. |
get_freshness | How current the export is: stale against a stated threshold (26 h by default), age in hours, last data date, per-file write times. |
list_metrics | Every available metric with unit, day count, and date range. |
get_health_metrics | Values for a metric (or all) over a date range, with aggregation (avg, sum, min, max, latest). Core data tool. |
get_trends | Compare the most recent N-day window against the prior N. Returns change, percent, direction (up/down/flat). |
compare_periods | A/B two arbitrary date windows for a single metric. Returns each aggregate plus the delta. |
get_structured_export | Clean structured JSON for chosen metrics and date range. Paginated with nextCursor. |
get_intraday | Hour-by-hour window from the app's hourly automations (app 1.4+). Live within-day view. |
query_health_data | Natural-language convenience: pass a plain question, get routed structured results. |
resolve_metric | Canonical name and unit for any spelling (steps, StepCount, hrv), unit variants with exact conversion formulas. Ambiguous words return candidates, never a guess. |
Every result carries a coverage block with the metric's real first and last date. This matters for get_trends in particular: the tool will tell you if the file does not hold enough history for the window you asked for.
Client-by-client config
The server command never changes. Only the config file location and JSON shape vary. Here is every one.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), or %APPDATA%/Claude/claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux). Merge into the mcpServers block:
{
"mcpServers": {
"health-export": {
"command": "node",
"args": ["/Users/you/.health-export-mcp/server.mjs"],
"env": {
"HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
}
}
}
}
Or drag the health-export.mcpb file into Claude Desktop Settings > Extensions for a no-JSON install. Either way, fully quit and relaunch Claude after.
Claude Code
Run the CLI command to add the server. This writes to user scope (~/.claude.json):
claude mcp add health-export \
-e "HEALTH_DATA_DIR=/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
-- node /Users/you/.health-export-mcp/server.mjs
Verify with claude mcp list. If pairing is enabled in the iOS app, add PAIRING_SECRET to the env block manually (not on the CLI, where it would land in shell history).
Cursor
Cursor uses the exact same JSON shape as Claude Desktop. Add the block above to ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project). Reload Cursor and check the MCP panel for a green health-export status.
ChatGPT Desktop
If your ChatGPT Desktop build (macOS) offers MCP servers in its settings (developer mode), add a server named health-export and paste:
{
"command": "node",
"args": ["/Users/you/.health-export-mcp/server.mjs"],
"env": {
"HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
}
}
Save, and the tools appear in the server list. If your build has no MCP option, use the webhook path instead.
Windsurf (Cascade)
Windsurf stores MCP config in ~/.codeium/windsurf/mcp_config.json. The shape mirrors Claude Desktop's mcpServers:
{
"mcpServers": {
"health-export": {
"command": "node",
"args": ["/Users/you/.health-export-mcp/server.mjs"],
"env": {
"HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
}
}
}
}
Restart Windsurf after saving. Cascade will show the health-export tools in its MCP tool picker.
Codex CLI
Codex CLI reads MCP servers from ~/.codex/config.toml, as a [mcp_servers.health-export] table with command, args and env. The values are the same ones every other client takes, shown here in JSON form; write them as that TOML table in config.toml:
{
"mcpServers": {
"health-export": {
"command": "node",
"args": ["/Users/you/.health-export-mcp/server.mjs"],
"env": {
"HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
}
}
}
}
Codex CLI picks up the config on restart. Ask it: "Use health-export tools to check my recent heart rate trends."
opencode
opencode uses a different JSON shape. The top-level key is mcp (not mcpServers), command is an array, and env goes under environment. Edit ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"health-export": {
"type": "local",
"command": ["node", "/Users/you/.health-export-mcp/server.mjs"],
"enabled": true,
"environment": {
"HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
}
}
}
}
OpenClaw
OpenClaw accepts the same shape as Claude Desktop's mcpServers block. The config file location varies by version; check OpenClaw's own MCP documentation for the path, then add the standard health-export entry with node server.mjs and HEALTH_DATA_DIR.
Real queries that work in every client
Once the server is connected, just talk to your agent. Here are prompts that work across Claude, Cursor, ChatGPT Desktop, Windsurf, Codex CLI, and opencode. The agent decides which tools to call.
You: Call get_mcp_status on my health-export server.
What data is available?
Agent: [calls get_mcp_status]
MetricBridge bridge active. Data source: iCloud sync.
194 metrics available. Most recent data: 2026-08-17.
Total workouts logged: 873.
You: Use my Apple Health data: what is my HRV trend over the last 14 days?
Agent: [calls get_trends → metric: hrv, window: 14]
Your HRV averaged 58 ms over the last 14 days.
Compared to the prior 14 days (55 ms), that is a +5.5% increase.
Direction: up.
You: Compare my sleep from this week to last week.
My data is in health-export.
Agent: [calls compare_periods → sleep_analysis; periodA: this week; periodB: last week]
This week: avg 7.2 h sleep, 2.1 h deep, 4.8 h core, 0.3 h rem.
Last week: avg 6.8 h sleep, 1.8 h deep, 4.5 h core, 0.3 h rem.
Deep sleep is up 17%, total sleep up 6%.
You: Run query_health_data: "How does my resting heart rate change on days
when I sleep less than 6 hours vs more than 7?"
Agent: [calls query_health_data]
On days following <6 h sleep, your RHR averages 58 bpm.
On days following >7 h sleep, your RHR averages 53 bpm.
That is a ~9% difference, which is a moderate deviation from
your personal baseline of 55 bpm.
No CSV, no copy-paste, no stale screenshots. Each query reads your latest export, the file your iPhone last wrote, on your own machine. The agent shows you its reasoning and the numbers behind it. The app's own baseline and deviation maths is published in the methods; all of it is wellness information, not medical advice.
What about clients that don't speak MCP?
ChatGPT web, Gemini, Grok, n8n, Home Assistant. These do not support MCP. For those, the MetricBridge iOS app can POST your data as JSON to a webhook endpoint you control. Every delivery is token-authenticated with a full send history. The MCP server and the webhook feed the same underlying export; choose the one your workflow needs.
Troubleshooting
"Agent says no tools are available"
The config was not loaded. Check that the JSON is valid (a trailing comma after the last entry breaks the whole file), you edited the correct file for your client, and you restarted the client. Claude Desktop, Cursor, Windsurf, and ChatGPT Desktop all read MCP config only at launch.
"Server is connected but says no data"
HEALTH_DATA_DIR points at the wrong folder, or the export has not synced yet. Confirm export is on in the iOS app, iCloud Drive has finished syncing .health-cache.json to this machine, and the path is absolute (no ~).
"Pairing secret rejected"
If you enabled pairing in the iOS app, the PAIRING_SECRET env var must match exactly. No trailing spaces, no stale codes. Re-copy from the app and update the env block.
"Wrong config format for my client"
The most common mistake: putting a Claude Desktop-shaped block into an opencode config. Claude Desktop uses mcpServers + env (object). opencode uses mcp + environment (object) + array-style command. Windsurf and Cursor use the same shape as Claude Desktop. Codex CLI uses a [mcp_servers.health-export] table in ~/.codex/config.toml, not .mcp.json. See each client's section above for the exact shape.
"Still not working?"
The fastest fix: ask the agent to call get_mcp_status and read back exactly what it reports. That tells you whether the server is up and whether the data source was found. Full setup recipes for every client also live in the open Agent Skill.
Frequently asked questions
Can I use the same MCP server with Claude Desktop and Cursor?
Yes. The same health-export-mcp server works with any MCP-aware client. Each client has a slightly different config file format, but the server command and HEALTH_DATA_DIR are identical. The config examples above cover every major client.
Does the MCP server send my health data to the cloud?
No. The server makes no outbound network calls. It reads a local JSON file and communicates with your AI agent over stdio (a local pipe within your computer), so nothing reaches us or a cloud AI from the server. The iOS app writes data to iCloud Drive, a folder, your LAN or a webhook you choose, never through a server we operate. Only the numbers your agent quotes enter its own model provider, as with any tool call.
What Apple Health metrics are available?
All 194 metrics MetricBridge exports (189 HealthKit types plus 5 derived glucose metrics). This includes heart rate, HRV, resting heart rate, sleep stages (deep, core, REM), steps, workouts, active energy, respiratory rate, blood oxygen, and more. Run list_metrics in any agent to see exactly which metrics your export covers.
Does Windsurf or Codex CLI support MCP servers?
Both do. Windsurf supports MCP through its Cascade config at ~/.codeium/windsurf/mcp_config.json. Codex CLI (from OpenAI) reads MCP servers from ~/.codex/config.toml ([mcp_servers.health-export] with command, args and env). See the per-client sections above for the exact JSON shapes.
Get Apple Health into every agent you use
One server, installed once: every MCP client answers from your real data, read-only, nothing to host.
Where it goes: the app reads Apple Health read-only and writes JSON to a folder you pick. Nothing reaches us or a cloud AI. What you get: all 194 metrics, 21 tools (19 read-only) and 23 prompts. Setup: about two minutes. Price: $24.99 one time after a 7-day free trial, not a subscription. Your phone: works on any iPhone the app runs on; Apple Intelligence is not needed for the export or MCP.