Connect Apple Health to Claude (and any MCP agent) — Step by Step

Want Claude to actually understand your sleep, HRV, and training load? This guide walks you through connecting Apple Health to Claude over MCP — the exact config, the one-click install, and the same recipe for Cursor, opencode, OpenClaw, and Hermes. Local-first, read-only, no accounts.

By Health Export AI · Updated 27 June 2026 · ~9 min read

Claude is genuinely good at reasoning over health data — spotting that your resting heart rate creeps up the day after a late night, or that your HRV recovers faster on rest weeks. But out of the box, Claude has no way to reach your Apple Health data. It can't open the Health app, and copy-pasting a giant CSV into a chat window is a dead end: the context and units get mangled, and the snapshot is stale the moment you export it.

The fix is MCP — the Model Context Protocol. With a small MCP server running on your own machine, Claude can call live, read-only tools against your real Apple Health data whenever you ask a question. This guide shows you exactly how to connect Apple Health to Claude via MCP, then how to do the same for every other MCP-aware agent.

What is MCP, in plain language?

MCP (the Model Context Protocol) is an open standard, introduced by Anthropic, that lets an AI agent talk to external tools and data sources through a consistent interface. Think of it as a universal adapter: instead of every app inventing its own bespoke plugin format, an MCP server advertises a set of tools, and any MCP-aware client — Claude Desktop, Claude Code, Cursor, opencode, OpenClaw — can call them.

For health data, that means Claude doesn't need a copy of your numbers baked into the conversation. Instead it calls tools like get_health_metrics, get_trends, or compare_periods on demand. The Health Export AI MCP server is zero-dependency Node — no Docker, no Python environment, no cloud bridge — and it exposes seven read-only tools:

• get_mcp_status — confirms the server can see your data
• list_metrics — lists which of the 190 metrics are available
• get_health_metrics — pulls raw values for a metric and date range
• get_trends — week-over-week or month-over-month trend math
• compare_periods — A/B two time windows (e.g. this week vs last)
• get_structured_export — a tidy structured bundle for deeper analysis
• query_health_data — flexible plain-language queries across metrics

Critically, the data never leaves your control. The iOS app reads Apple Health read-only and writes a small JSON file to a destination you pick — your iCloud Drive, a synced folder (Dropbox, Google Drive, OneDrive, Syncthing…), your local network, or a webhook you run. The MCP server simply reads that folder. Nothing transits the developer's servers. For the bigger picture on the export side, see the pillar guide: Export Apple Health data to JSON for AI.

Before you start: two prerequisites

1. Install Health Export AI on iOS, grant Apple Health (read-only), turn on export, and choose a destination. The simplest is iCloud Drive — the OS syncs it to your Mac with zero extra setup.
2. Have Node.js installed on the computer where Claude runs (any recent LTS is fine). The MCP server is a single node command — no global install, no package manager gymnastics.

Connect Apple Health to Claude Desktop

This is the headline setup. There are two routes — a one-click bundle, and a hand-edited config. Use whichever you prefer.

Route A The one-click .mcpb bundle

Claude Desktop supports .mcpb (MCP Bundle) files — a single, self-contained package that installs a server without touching JSON by hand. Download health-export.mcpb from the homepage and double-click it. Claude Desktop opens its install dialog, prompts you for the data folder (your HEALTH_DATA_DIR) and, if you've enabled pairing, the secret. Confirm, then restart Claude Desktop. That's the entire setup. The bundle ships its own copy of the server, so you don't need to manage a separate file.

Route B Edit the config manually

If you'd rather see exactly what's wired up, edit Claude Desktop's config file directly. Its location depends on your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Merge a health-export entry into the mcpServers block (leave any existing servers in place):

{
  "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"
      }
    }
  }
}

Swap in your real SERVER_PATH and HEALTH_DATA_DIR. If you turned on pairing in the iOS app, add one more line to env: "PAIRING_SECRET": "your-pairing-code". Save the file and fully quit and reopen Claude Desktop — it only reads the config at launch.

The same setup for Claude Code, Cursor, opencode, OpenClaw & Hermes

The beauty of MCP is that the server never changes — only where each client wants its config. Here's the short version for the rest of the agent set.

Claude Code

Let the CLI write the config for you:

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"

That writes user scope (~/.claude.json); add --scope project to write a shared .mcp.json instead. Verify with claude mcp list. If pairing is on, avoid passing the secret on the command line (it lands in shell history) — add "PAIRING_SECRET" to the entry's env in the config file by hand instead.

Cursor

Cursor uses the same mcpServers shape as Claude Desktop. Drop the identical block into ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project), reload Cursor, and check the MCP panel for a green health-export.

opencode & OpenClaw

opencode uses a different shape — note the top key is mcp, command is an array, and the env key is environment. Edit opencode.json (project) or ~/.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 consumes standard MCP servers; its config file and key can vary by version, so check OpenClaw's own MCP docs for the exact location, then add a health-export block using the same node server.mjs command and HEALTH_DATA_DIR shown above.

Hermes

One nuance worth flagging: Hermes is an Elixir library for building MCP servers, not a click-install agent like the others. If you're building a Hermes-based client or server, point it at the same node server.mjs command with HEALTH_DATA_DIR in the environment — the Health Export AI server speaks standard MCP over stdio (and Streamable HTTP), so any compliant host can drive it.

A worked example: ask Claude about your week

Once health-export is connected, you just talk to Claude normally — it decides which tools to call. Try a real question:

You: How did my recovery trend this week compared to last week?
     Use my Health Export data.

Claude: [calls get_trends → metric: hrv, period: 7d]
        [calls compare_periods → hrv, steps, resting_hr; this week vs last]

        Your HRV averaged 61 ms this week, up 4.4% from 58 ms last week.
        Resting heart rate dropped from 56 to 55 bpm (-2.4%), and sleep held
        steady at ~7.1 h. Together those point to better recovery — the HRV
        gain alongside a falling resting HR is the classic "well-recovered"
        signal. Your step count was also 6.6% higher, so you recovered while
        training more, not less.

No CSV, no pasting, no stale snapshot. Claude pulled live numbers from your local export, did the comparison, and gave you a plain-language read. Ask a follow-up — "plot resting HR for the last 30 days" or "compare weekday vs weekend steps" — and it calls the right tools again. For more query ideas across agents, see querying Apple Health with ChatGPT and Cursor.

Troubleshooting

Claude shows no health-export tools at all

The config wasn't loaded. Confirm the JSON is valid (a stray comma breaks the whole file), that you edited the right file for your OS, and — most commonly — that you fully quit and relaunched Claude Desktop. The app reads mcpServers only at startup.

The server connects, but says "no data" or "source missing"

Your HEALTH_DATA_DIR is pointing at the wrong folder, or the export hasn't landed there yet. Check three things: export is turned on in the iOS app; iCloud Drive (or your synced folder) has finished syncing the .health-cache.json file to this computer; and the path in your config matches that folder exactly, with ~ expanded to your real home directory.

Permission or pairing errors

If you enabled pairing in the app, the PAIRING_SECRET in your config must match the iOS pairing code exactly. A trailing space or a stale code will be rejected. Re-copy it from the app and update the env block.

Wrong env key for your client

Remember the shapes differ: Claude Desktop, Claude Code and Cursor use mcpServers with an env object; opencode and OpenClaw use mcp with an environment object and an array-style command. Putting env into an opencode file (or vice-versa) silently does nothing.

Still stuck?

The fastest diagnostic is to ask the agent to call get_mcp_status and read back exactly what it reports — it tells you whether the server is up and whether the data source was found. Full setup recipes for every client live in the open Agent Skill, and you can always reach a human via Support.

Related reading

• → Export Apple Health data to JSON for AI (the pillar guide)
• → Apple Health JSON vs CSV vs XML — which format AI agents actually want
• → Query your Apple Health data with ChatGPT and Cursor
• → Health Export AI — product overview & setup
• → health-export-mcp — the zero-dependency MCP server on GitHub