Query Apple Health with Any AI Agent

Multi-client MCP setup guide (2026). One server, eight clients, zero dependencies. Real config blocks for Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, Codex CLI, opencode, and OpenClaw. Plus the exact queries that work across all of them.

By Health Export AI · Updated 18 August 2026 · ~11 min read

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 (84 kB on disk). 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:

1. Health Export AI 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).
2. Node.js on the computer where your AI agents run. Any recent LTS works. The server is a plain node invocation: no global install, no Docker, no Python.

The server: what tools does it expose?

Eight read-only tools, all local. The table below shows what each one does so you know what to ask your agent.

Tool	What it returns
get_mcp_status	Health check: data source, metric count, most recent data date. Call this first.
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.

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

ChatGPT Desktop (macOS) supports MCP servers in its settings. Open Settings > Features > MCP Servers, click "Add MCP Server," 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"
  }
}

Name it health-export and save. The ChatGPT desktop app immediately connects to the server and shows available tools.

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

OpenAI's Codex CLI reads MCP config from .mcp.json in the project root or ~/.codex/mcp.json:

{
  "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]
       Health Export bridge active. Data source: iCloud sync.
       142 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 hits live data from your iPhone, answered from your local export. The agent shows you its reasoning and the numbers behind it.

What about clients that don't speak MCP?

ChatGPT web, Gemini, Groq, n8n, Home Assistant. These do not support MCP. For those, the Health Export AI 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 .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.

Related reading

• → Connect Apple Health to Claude via MCP (single-client guide)
• → Connect Apple Health to Cursor (single-client guide)
• → Connect Apple Health to ChatGPT via Webhook
• → Best Apple Health MCP Servers Compared 2026
• → Local-First Health Analytics with Claude Code
• → Health Export AI · product overview & setup