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

Cursor is the fastest-growing MCP client, and it's the best tool for running health-data queries alongside your code. This guide walks you through wiring your Apple Health data into Cursor via MCP — the exact mcp.json config, how to verify it in Cursor's MCP panel, and real Composer queries you can run today.

By Health Export AI · Updated 25 July 2026 · ~9 min read

Cursor supports MCP natively since v0.45. Pair it with the Health Export AI 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. Your data stays local and Cursor calls read-only tools on demand.

What you need before starting

  1. Health Export AI on iOS — install it, grant read-only Apple Health access, turn on export. iCloud Drive is the simplest destination — 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 seven tools the server advertises: get_mcp_status, list_metrics, get_health_metrics, get_trends, compare_periods, get_structured_export, and query_health_data. 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.2.0"}

        The server is running and sees your health data cache.
        All 7 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's a
meaningful improvement — a falling resting HR alongside stable
training volume usually signals better cardiovascular recovery.
If you want to check sleep or HRV for the same period, let me
know and 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.

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? Health Export AI handles the export step — all 190 metrics as local JSON, with the open-source MCP server (GitHub).

Get Apple Health into Cursor in two minutes

190 metrics, seven live MCP tools, fully local. Free 7-day trial — no account, nothing on our servers.

Get the app & setup View the open-source MCP on GitHub Download on the App Store

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. Health Export AI's servers are not involved — no telemetry, no data transit, no accounts.

What if I don't use iCloud Drive?

The iOS app supports Dropbox, Google Drive, OneDrive, local network shares (SMB), Syncthing, or a webhook. Just point HEALTH_DATA_DIR at whichever folder holds your .health-cache.json.

Related reading

Health Export AI · Apple Health → your AI agent, privately. · Home · Privacy · Terms · Support