Apple Health MCP Server

An MCP server that exposes Apple Health data as tools queryable by LLMs (Claude, Copilot, etc.).

Architecture

exportación.xml (Apple Health)
        │
        ▼
  preprocess.py  ──►  data/*.parquet   (run locally on Mac)
                              │
                              ▼  (sync_to_fly.sh, over plain HTTPS)
                     Fly.io: fjcabello-apple-health-mcp
                        ├─ wrapper.py (FastMCP app + api_key ASGI gate, port 8080)
                        └─ /data volume (persistent, 1GB) ─ loaded by server.py
                              │
                              ▼
         apple-health-fly-mcp-worker (Cloudflare Worker, OAuth gateway)
                              │
                    https://apple-health-fly-mcp-worker.fjcabello.workers.dev/mcp

The server loads Parquet files at startup (~1-2 s) and caches them in memory. If they are not found, it falls back to parsing the XML directly. server.py is never modified for deployment concerns — wrapper.py wraps it with the api_key auth gate and the admin sync endpoints (see "Deploy to Fly.io" below).

---

Requirements

• Python 3.11+
• pyarrow (for Parquet support)

pip install -r requirements.txt
pip install pyarrow

requirements.txt

mcp[cli]>=1.0.0
lxml>=5.0.0
pandas>=2.0.0
pyarrow>=15.0.0
uvicorn>=0.30.0

---

Data update workflow

1. Export from iPhone

Health → profile → Export All Health Data → produces a ZIP containing exportación.xml. Unzip it so the file lands at ../apple_health_export/exportación.xml (relative to this repo), or pass a custom path.

2. Sync to Fly.io

cd ~/Personal/apple_health/apple_health_mcp
./sync_to_fly.sh

This single script:

1. Runs preprocess.py (XML → data/*.parquet, ~20-25 files, one per metric type)
2. Uploads every Parquet file to the Fly volume via PUT /admin/upload/<filename>?api_key=... (plain HTTPS — SSH/SFTP tunnels to Fly are blocked on this network)
3. Calls POST /admin/reload?api_key=... to clear the in-memory cache, so the next tool call picks up the fresh data — no machine restart needed

Both /admin/* routes require the API_KEY Fly secret as a query param (see wrapper.py). The key is read from .fly_secret_local (gitignored) or the environment.

3. Automated sync via Health Auto Export

Instead of manually exporting the Apple Health ZIP, the Health Auto Export iOS app can push data automatically via a webhook, which upserts directly into the Parquet files on the Fly volume (no XML/preprocess step needed). This is defined in server.py (ingest_app) and wired into wrapper.py's router.

Endpoint (calls Fly directly, not through the Cloudflare Worker):

POST https://fjcabello-apple-health-mcp.fly.dev/ingest
GET  https://fjcabello-apple-health-mcp.fly.dev/ingest/inspect   (last payload received, for debugging)

Authentication: header x-api-key: <secret> or query param ?api_key=<secret>, checked against the INTERNAL_SECRET Fly secret (kept equal to API_KEY for simplicity — set both with the same value). This is intentionally separate from the Cloudflare Worker's OAuth, since the iOS app can only set a header, not go through the OAuth flow.

Configure one automation per data type in Health Auto Export (the app only allows one data type per automation): Health Metrics, Workouts, etc. — pick the metrics listed in config.py → HK_TYPE_MAP. Format JSON, export version v2, incremental date range, header x-api-key set to the shared secret.

Each /ingest call upserts only the metrics/workouts present in that payload (dedup by startDate, or startDate + activityType for workouts) and clears the in-memory cache so the next MCP tool call reloads fresh data — no restart needed.

Deploy to Fly.io

The server runs as a Docker container on Fly.io (app fjcabello-apple-health-mcp, region ams), fronted by wrapper.py (an ASGI router that gates /mcp and /admin/* behind API_KEY, and forwards /ingest* to server.py's own-auth ingest_app — mirrors the proxy.cjs pattern in garmin-connect-mcp). Parquet files live on a persistent Fly volume mounted at /data, not baked into the image.

First-time setup

fly auth login
fly apps create fjcabello-apple-health-mcp
fly volumes create apple_health_data --region ams --size 1 --app fjcabello-apple-health-mcp
fly secrets set API_KEY=$(openssl rand -hex 32) --app fjcabello-apple-health-mcp
fly secrets set INTERNAL_SECRET=<same value as API_KEY> --app fjcabello-apple-health-mcp

Continuous deployment

.github/workflows/deploy.yml auto-deploys to Fly.io on every push to main, using a FLY_API_TOKEN repo secret (fly tokens create deploy --app fjcabello-apple-health-mcp).

Why CI instead of fly deploy locally: on this network, Fly's remote "depot" builder and SSH/SFTP tunnels hang indefinitely / fail the WebSocket handshake (corporate SSL/proxy inspection). Deploying from a GitHub-hosted runner avoids this entirely.

Seeding / updating data

See "Data update workflow" above — use ./sync_to_fly.sh, not SSH.

---

Running locally (development)

python server.py
# Listens on http://0.0.0.0:8001/mcp

Optional environment variables:

Variable	Default	Description
APPLE_HEALTH_DATA_DIR	./data	Directory containing .parquet files
APPLE_HEALTH_EXPORT	../apple_health_export/exportación.xml	XML fallback path

---

Available MCP tools

Tool	Description
health_summary	Overview of all available data types, record counts and date ranges
get_steps	Daily step counts
get_heart_rate	Heart rate per day (mean / min / max)
get_resting_heart_rate	Daily resting heart rate
get_sleep	Sleep analysis by stage (Core, Deep, REM, Awake)
get_workouts	Workout sessions, filterable by type and date
get_body_metrics	Weight (kg), BMI, body fat %, lean body mass
get_activity_energy	Active/basal energy burned, distance, flights climbed
get_nutrition	Nutritional intake (calories, protein, carbs, fat)
query_health_data	Generic query for any available metric

All tools accept optional start_date and end_date parameters in YYYY-MM-DD format.

Available metrics for query_health_data

steps, heart_rate, resting_hr, active_energy, basal_energy, distance_walk, distance_cycling, flights_climbed, sleep, body_mass, bmi, body_fat, lean_body_mass, walking_speed, walking_steadiness, dietary_energy, dietary_protein, dietary_carbs, dietary_fat

---

Cloud access (OAuth)

The Cloudflare Worker adds OAuth 2.0 authentication for remote access from Claude.ai or VS Code.

Public URL: https://apple-health-fly-mcp-worker.fjcabello.workers.dev/mcp

VS Code configuration

// .vscode/mcp.json
{
  "servers": {
    "apple-health-cloud": {
      "type": "http",
      "url": "https://apple-health-fly-mcp-worker.fjcabello.workers.dev/mcp"
    }
  }
}

Worker source

See fjcabello/apple-health-fly-mcp-worker (../apple-health-fly-worker/ in the local workspace). Same multi-MCP OAuth gateway pattern as garmin-connect-mcp's mcp-oauth-gateway.