Connect Apple Health to Cursor: Step-by-Step MCP Setup

By the end of this page Composer answers "how did my resting heart rate trend this month?" from your real Apple Health data, read-only, on your own Mac. The exact mcp.json, how to verify it in Cursor's MCP panel, and real queries you can run today.

By MetricBridge · Published 25 July 2026 · Updated 27 October 2026 · ~9 min read

AI-assisted, human reviewed. How we use AI

Cursor supports MCP natively since v0.45. Pair it with the MetricBridge MCP server and Composer can query your Apple Health metrics live: "How did my resting heart rate trend this month?" or "Show me HRV data for nights I slept less than 6 hours." The setup takes two minutes: no Docker, no cloud account, no pasting CSV files. The server reads a file on your Mac and makes no network calls; Cursor calls read-only tools on demand. The MCP page has every tool and client config.

What you need before starting

  1. MetricBridge on iOS: install it, grant read-only Apple Health access, turn on export. iCloud Drive is the simplest destination because it syncs to your Mac automatically.
  2. Node.js: any recent LTS. The MCP server is a single .mjs file with zero dependencies beyond Node itself. No npm install, no Docker, no venv.
  3. Cursor v0.45+: check your version in Settings → About.

The two values you'll reuse everywhere

SERVER_PATH: absolute path to server.mjs wherever health-export-mcp lives on disk.

HEALTH_DATA_DIR: absolute path to the folder holding your .health-cache.json. With iCloud on macOS:

~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents

Expand ~ to your home path: config files don't understand the tilde.

Configure Cursor

Cursor reads MCP servers from mcp.json. Drop it at the global level (~/.cursor/mcp.json) for all projects, or at the per-project level (<project>/.cursor/mcp.json) to scope it. The config shape matches Claude Desktop's mcpServers block. Create or edit the file and add this entry:

{
  "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 paths. If you enabled pairing in the iOS app, add "PAIRING_SECRET": "your-code" to env. Save the file. Unlike Claude Desktop, Cursor live-reloads MCP config; no restart needed. Use Cmd+Shift+P → "MCP: Reload MCP Servers" to pick up changes.

For per-project usage, Cursor prioritizes the project-level mcp.json over the global one. This is useful when you're building a health app and want the server scoped to that codebase, or when you share the config in version control with your team.

Verify the connection

Open Cursor, press Cmd+Shift+P, and select "MCP: Show MCP Panel". You should see health-export with a green status dot. Click to expand. It lists the 16 tools the server advertises: 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. Red or disconnected means the server failed to start. Verify node is on your PATH, the paths are correct (tilde expanded), and the JSON is valid.

Run your first query in Composer

Cursor's Composer doesn't auto-discover MCP tools the way Claude Desktop does. You need to name the server in your prompt. Start with a status check:

You: Use the health-export MCP server to call get_mcp_status
      and tell me what it reports.

Cursor: Calling get_mcp_status...
        {"status":"ok","dataSource":"/Users/you/Library/Mobile Documents/...","serverVersion":"1.7.3"}

        The server is running and sees your health data cache.
        All 16 tools are available.

Once confirmed, try real queries. Here's what a trend call looks like in Composer. The raw tool output appears inline, then the model interprets it:

You: Call get_trends on health-export for resting heart rate over
      the last 14 days and tell me if there's a meaningful change.

► Tool Result: get_trends(metric: resting_hr, period: 14d)

{
  "metric": "HKQuantityTypeIdentifierRestingHeartRate",
  "period": "14d",
  "avg": 56,
  "prev_avg": 58,
  "change_pct": -3.45,
  "unit": "bpm",
  "samples": 280
}

Cursor: Your resting heart rate averaged 56 bpm over the last 14
days, down 3.5% from 58 bpm the prior fortnight. That is a
deviation from your own recent baseline, worth reading next to
your training volume for the same period. If you want sleep or
HRV for the same window, I'll call compare_periods.

Notice what didn't happen: no CSV attachment, no copy-paste, no unit conversion. The model gets clean typed data and operates on it directly. Try these prompts next:

  • "Use health-export to call list_metrics, then for the top 5 by data count, call get_health_metrics for the last 30 days and summarize any deviations from my personal baseline."
  • "Use compare_periods from health-export to compare my HRV, sleep hours, and step count this week vs last week."

For more query ideas across agents, see querying Apple Health with ChatGPT and Cursor. How the app itself computes baselines and deviations is published in the methods; everything here is wellness information, not medical advice.

Troubleshooting

"health-export" shows as disconnected

Open Help → Toggle Developer Tools and check the Console tab for Node errors. Common causes: missing Node runtime, wrong SERVER_PATH, or a permission issue on the data directory. If you use a version manager like nvm, provide the full Node path ($(which node)) in the command field.

Cursor can't see the tools in Composer

You must name the server in your prompt: start with "Use the health-export server..." Otherwise Cursor ignores your MCP config and falls back to built-in tools.

Server connects but says "no data found"

Your HEALTH_DATA_DIR is wrong or the export hasn't synced. Verify three things: export is on in the iOS app; .health-cache.json exists at that path; iCloud Drive (or your sync provider) has finished downloading it. Run ls -la "<your-HEALTH_DATA_DIR>" in terminal to check.

Doing this yourself? MetricBridge handles the export step: all 194 metrics as local JSON, with the open-source MCP server (GitHub).

Get Apple Health into Cursor in two minutes

Composer answers from your real data, read-only, nothing to host. The app does the export; the open-source server does the rest.

Start my 7-day free trial Install the MCP server Source on GitHub

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, 16 read-only tools and 22 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.

Frequently asked questions

Does Cursor support MCP natively, or do I need a plugin?

Cursor has native MCP support since v0.45. No plugins needed: configure your servers in mcp.json and use them from Composer.

Can I use the same MCP server for Cursor and Claude Desktop at the same time?

Yes. Each client spawns its own Node.js process, so they don't conflict. Both can query the same .health-cache.json file simultaneously.

Does Cursor send my health data to any remote server?

No. The MCP server reads a local JSON file on your machine and never phones home. MetricBridge's servers are not involved: the MCP server has no telemetry, no data transit, no accounts.

What if I don't use iCloud Drive?

In the app you pick an On My iPhone or iCloud Drive folder (iOS greys out Dropbox, Google Drive and OneDrive in its folder picker). Your desktop sync client (Dropbox, Google Drive, OneDrive, Syncthing, or rclone) carries that folder to your computer; SMB shares and a webhook also work. Just point HEALTH_DATA_DIR at whichever folder holds your .health-cache.json on this machine.

Related reading