Health Access MCP
Reads Apple Health and Apple Watch data (workouts, heart rate series, intervals, sleep, HRV, resting heart rate, weight, steps, VO2max, ECGs, Effort ratings) and writes AI-generated workout plans back to the Watch's Workout app as custom structured workouts via WorkoutKit.
Supported sync folder option (checked during folder auto-detection) for the exported health data folder, so the AI can read workouts and daily metrics from a Box-synced directory.
Auto-detected sync folder for the exported health data folder, letting the AI read workouts and daily metrics from a Dropbox-synced directory.
Auto-detected sync folder for the exported health data folder, letting the AI read workouts and daily metrics from a Google Drive-synced directory.
One of the auto-detected sync folders where the app exports health JSON files; the MCP server locates the Health Access folder here so the AI can read workouts, days and briefing data.
Supported sync folder option for the exported health data folder, so the AI can read workouts and daily metrics from a Proton Drive-synced directory.
Health Access MCP
Apple won't let your AI read your Watch. This does.
Health Access is middleware. It does the one thing Apple requires a phone app for, writing your workouts and daily health data as JSON into a folder you pick, and then it gets out of the way. Your AI reads that folder, through the MCP or just as files. If it writes you a workout plan, one tap puts it on your Watch, or none with Automatic on.
Free and open source (MIT), no account, no server. If you are looking for a free alternative to Health Auto Export to get Apple Health data to an AI, this is one: the two side by side. Short answers to the usual questions: questions and answers.
Site: healthaccessmcp.com (built from site/). For an AI: llms.txt, llms-full.txt. Server: healthaccess-mcp on npm, listed in the official MCP registry as com.healthaccessmcp/healthaccess-mcp. What changed when: CHANGELOG.md.
Name. The project ran under the codename "Tide" until 2026-10-25 and is now Health Access MCP. The repository directory on disk is still
~/Developer/tidefor now; everything inside uses the new names. Files and settings written before the rename keep working: thetide.*schema ids,TIDE_DIR,~/.config/tide/config.tomland thetide://resource URIs are accepted as aliases forever. Seedocs/schema.mdanddocs/mcp.md.
Who this is for
You have an Apple Watch and an AI coach. Claude, ChatGPT, Cursor, a local model, whatever. You want it to see your actual sessions, heart rate, sleep and weight instead of what you remember to type. That is the main job.
Or a human coach. Same folder, shared with a person. They get the real splits instead of a screenshot.
Second job: plans back to the Watch. Your AI writes the session as a small JSON file. The app turns it into a custom workout with the step names on your wrist. No file import, no Watch app to configure.
Not for: looking at charts in the app. There are none. The AI is the user of this data, so the effort goes into the files, the MCP and the docs, not into screens.
Related MCP server: health-mcp
The order of things
Once, about five minutes, you
Install the app: Health Access MCP on the App Store, free. Or build it from this repository with Xcode.
Pick a folder. Anything the iOS Files app can see: iCloud Drive, Dropbox, Google Drive, OneDrive, Proton Drive, a NAS, local. The one rule: your AI has to be able to reach the same folder, so pick one that syncs to the computer where the AI runs.
Allow Health access (read only, you choose the types) and notifications (one kind only: "Your AI wrote S27", when a plan arrives).
Give it to your AI. Paste the message the app copies; Claude or Cursor register
npx -y healthaccess-mcp, which finds your folder on its own. An AI that cannot run a program, such as ChatGPT, works from the summary in the same message.
Every workout, nobody
You end a workout on the Watch.
Next time the phone is unlocked, the app writes
workouts/2026-05-14_0712_PoolSwim_7A1C3E90.jsoninto the folder: distance, time, heart rate every few seconds, every interval with its name, every length with stroke and SWOLF. Vitals land once a day.The folder syncs to your computer.
Your AI reads it. No app on that side.
Sometimes, one tap, you
Rate the session on your Watch when it asks. Effort is the one number nobody else can measure, and it turned out to matter more than heart rate. Apple exports your Effort score and the app picks it up; the app itself never asks.
When your AI has written a plan: tap "Put on Watch" in the Import tab, or switch on "Put new plans on my Watch automatically" once and skip even that.
Whenever you ask, your AI
Reads sessions, vitals and trends through the MCP, or reads the JSON directly. The folder is the API.
Writes a workout plan into
plans/with the day and time you said. It shows up in the app's Import tab.Works without the MCP too: the folder also holds
briefing.md, a one-page summary any AI can read.
Two honest limits, both Apple's. Health data can only be read while the phone is unlocked, so a workout finished with the phone in the bag exports the next time the phone is unlocked, not before. And the Watch keeps its own pool length setting, the plan can't set it.
Connect your AI, first thing
claude mcp add --scope user healthaccess -- npx -y healthaccess-mcpThat is Claude Code. For Claude Desktop, Cursor, LM Studio and most other hosts the config entry is {"command": "npx", "args": ["-y", "healthaccess-mcp"]}. The server finds the Health Access folder on its own (iCloud Drive, then Dropbox, Google Drive, OneDrive, Box, then ~/Documents); --dir "<folder>" names it yourself. Node.js 18 or newer is the only requirement. Or paste this to your AI and let it do the setup (the app puts it on your clipboard):
Set up the Health Access MCP for me.
Docs for you: https://healthaccessmcp.com/llms.txt
The server runs with: npx -y healthaccess-mcp
It finds my Health Access folder on its own.
Register it in this app, then list my last 5 workouts.One page per client: Claude Code, Claude Desktop, Cursor, ChatGPT (files only today; ChatGPT does not launch local MCP servers), local models. The full install and setup reference is docs/mcp.md.
What the AI gets
Tool | Does |
| Compact rows, newest first. One line per session, written for an LLM. |
| One session in full: every interval with its name, pace and heart rate, zone seconds, lengths, recovery heart rate, your effort rating. Heart-rate series only if asked. |
| Resting heart rate, HRV, sleep, weight, steps, VO2max by day. |
| Per week: volume, sessions, easy-zone share, mean effort, and the cardiac cost trend (beats per 100 m). |
| Stores the effort you told the AI. The AI must ask you, never guess. |
| Validates a session (labels under 40 characters, zones 1 to 5) and writes it to |
| Whether the app has put a plan on the Watch yet: pending, scheduled, failed or cancelled. |
| Every plan in |
| Everything Health holds for a day or a range, in groups: activity, heart, sleep, body, mind and more. |
| Every Health type, whether it has data and where it was exported. |
| Age, sex, height and the other characteristics from |
| Every ECG summary, newest first. |
Thirteen tools. Arguments, return shapes and heuristics: docs/mcp.md. Resources: healthaccess://index, healthaccess://workout/<id>, healthaccess://briefing. The healthaccess CLI has the same views (list, show, summary, rate, plan push|status|list, day, days, catalog, profile, ecgs, briefing, prompts, doctor); from npm it runs as npx -y -p healthaccess-mcp healthaccess <command>.
Ideas for your AI
Eleven prompts ship with the docs as suggestions, not as a step of the setup, in two groups and for any sport. Use them, change them or ignore them. Each asks first, reads second, writes last. Export: weekly check-in, explain my last session, am I overdoing it, sleep and recovery, long-term trends, a summary for a coach or doctor. Import: plan my next session, plan my week, change my plan, build up to a goal, make my workout a Watch workout. Source: docs/prompts.md; scripts/sync-prompts.py copies it into the app and the site.
The folder
<folder>/
index.json one row per workout, newest first (app)
briefing.md one page any AI can read (app)
workouts/<date>_<time>_<Activity>_<uuid8>.json one per workout (app)
days/<date>.json one per day, every Health group with data (app; vitals/<date>.json kept for older readers)
catalog.json, profile.json what Health holds and the athlete's characteristics (app, v0.4)
plans/<id>.json written by the MCP or CLI (push_plan)
plans/<id>.status.json written by the app: scheduled (with the time), failed, or cancelled after "Remove from Watch"
mcp/clients/<id>.json presence file written by the MCP: client, machine, counts; never arguments or resultsNothing else writes, nothing deletes. The complete contract with every field is docs/schema.md; a readable version with a trimmed example is site/docs/files.html. A complete synthetic folder, generated and not a real person, is examples/: point the CLI at it with healthaccess --dir examples list. The plan format and the "Put on Watch" flow: site/docs/plans.html.
Limits
Health data is readable only while the phone is unlocked (Apple); exports wait until it is.
The Watch keeps its own pool length; plans cannot set it (WorkoutKit has no parameter).
Step names on the Watch need iOS 18; labels over 40 characters are cut.
Plans: run, indoor run, walk, hike, cycle, indoor cycle, pool and open-water swim, indoor row, HIIT and elliptical (the last two take time goals only). Plans land in the Watch's Workout app, not in Apple Fitness+.
Automatic Put on Watch runs when the app opens or iOS wakes it, within hours; iOS does not wake apps the second a file arrives.
Apple's "Add to Watch" sheet does not report back; the app asks and records
method: preview.The npm server contains no network code. The app's usage statistics are off by default and never carry a health value, a file name or a path. The exact event names: site/docs/privacy.html.
Repository layout
app/iOS app (SwiftUI, iOS 17+). Xcode target and schemeHealthAccess, productHealth Access, bundle idcom.healthaccessmcp.app. Project generated with XcodeGen fromapp/project.yml(never hand-edit the.xcodeproj). Details inapp/README.md.core/Rust cratehealthaccess-core(libhealthaccess_core): data contract models, folder store, zone math, derived training views, the Apple.workoutcodec.mcp/Rust cratehealthaccess-mcp: the MCP server over stdio (binaryhealthaccess-mcp).cli/Rust cratehealthaccess-cli: thehealthaccesscommand-line tool.examples/a synthetic Health Access folder (generate.pyrewrites it; tests, docs and the site quote it).docs/north-star.md(the acceptance checklist every build is checked against),schema.md(the folder contract),mcp.md(install, client setup, tools, CLI, distribution),prompts.md(the eleven prompts, source of truth),positioning.md(canonical copy),brand.md(name, design language),export-coverage.md,phase0-spike.md(findings).npm/the npm launcher package,npm/server.json(MCP registry entry),npm/test/(end-to-end test against a local registry).claude-plugin/the Claude plugin: the MCP server and the prompts as skills. This repository is its own plugin marketplace (.claude-plugin/marketplace.json):claude plugin marketplace add leonhardprinz/healthaccess-mcp, thenclaude plugin install healthaccess-mcp@healthaccess. Not in Anthropic's directory.scripts/bump-version.sh,build-npm.sh,publish-npm.sh,publish-registry.sh,sync-prompts.py,build-site.sh,deploy-site.sh,make-og.py.site/the static docs site: plain HTML, one CSS file, self-hosted fonts.scripts/build-site.shstages it with/ref/and/examples/intodist/site,scripts/deploy-site.shdeploys it to Cloudflare Workers (wrangler.jsonc,site-worker/). Preview:scripts/build-site.sh && python3 -m http.server -d dist/site 8000.
The master plan is kept outside the repository.
Build the app (free personal team)
Xcode installed, signed in with your Apple ID (Xcode, Settings, Accounts). A "Personal Team" appears.
iPhone: Settings, Privacy & Security, Developer Mode on (reboot).
cd app && xcodegen generate && open HealthAccess.xcodeprojIn Xcode: Signing & Capabilities, Team = your Personal Team. Change the bundle id if it collides.
Plug in the phone, select it, run. First run: trust the developer certificate on the phone (Settings, General, VPN & Device Management).
Free team: the build expires after 7 days; run again.
Headless build and install commands are in app/README.md.
Build the Rust half
cargo install --path mcp --locked # -> ~/.cargo/bin/healthaccess-mcp
cargo install --path cli --locked # -> ~/.cargo/bin/healthaccess
healthaccess --dir "<your folder>" doctorThen register your build instead of the npm one: claude mcp add --scope user healthaccess -- /Users/<you>/.cargo/bin/healthaccess-mcp. Website: scripts/deploy-site.sh builds dist/site (site, /ref/ docs, /examples/) and deploys it to healthaccessmcp.com on Cloudflare Workers. npm: see "Install" in docs/mcp.md. The CI gate (cargo test, clippy, fmt, release build) is listed in docs/mcp.md.
License
MIT for the MCP server, the core crate and the CLI (Cargo.toml). Apple, Apple Watch, Apple Health and HealthKit are trademarks of Apple Inc.; this project is not affiliated with Apple.
Available Tools
13 toolsget_catalogARead-onlyIdempotent
What Health holds for this athlete: every HealthKit type with has_data, sample count over 90 days, first and last date and where the app exported it, plus the coverage check against the identifier list this build knows (types with data not exported, unknown types with data).
Inputs: no named parameters.
get_dayARead-onlyIdempotent
Everything Health holds for one day, in groups: activity (rings, steps, distances, energy, physical effort), heart (resting, HRV, VO2max, events), respiratory, sleep, body, blood, mobility, hearing, nutrition, mind, symptoms, cycle, medications, hygiene, uv, wheelchair, audiogram, vision. Only groups with data are present.
Inputs: date (required).
get_daysARead-onlyIdempotent
The day files of a date range (at most 366 days), oldest first, optionally reduced to the groups you name, so you can follow sleep, resting heart rate or rings over time in one call.
Inputs: to (required), from (required), groups.
get_plan_statusCRead-onlyIdempotent
Whether a plan reached the Watch: pending (not on the Watch yet), scheduled (with scheduled_for), failed (with the error) or cancelled (the athlete removed it from the Watch).
Inputs: id (required).
get_profileARead-onlyIdempotent
The athlete's characteristics as Health has them: age and birth year, biological sex, blood type, wheelchair use, move mode, skin type.
Inputs: no named parameters.
get_vitalsARead-onlyIdempotent
Resting heart rate, HRV, sleep, weight, steps, VO2max and blood pressure by day for the last N days, with simple averages.
Inputs: days.
get_workoutARead-onlyIdempotent
One session in full: every part with its label, distance, pace and heart rate (also as parts_text lines you can quote), zone seconds, pool lengths with stroke and SWOLF, recovery heart rate, the athlete's effort and feel, cardiac cost. Heart-rate series only if you ask.
Inputs: id (required), include_laps, include_hr_series.
list_ecgsARead-onlyIdempotent
Every ECG the Watch recorded, newest first: time, classification, symptoms status, average heart rate, sampling frequency, algorithm version, device, and whether a voltage file sits next to it.
Inputs: no named parameters.
list_plansARead-onlyIdempotent
Every plan in plans/ with its state, planned distance and time, newest first.
Inputs: no named parameters.
list_workoutsARead-onlyIdempotent
Compact rows, newest first, one line per session written for you: date, sport, distance, time, average heart rate, effort with its source and whether it is rated. Filter by start date and sport.
Inputs: limit, since, sport.
push_planA
Validates a session (sport one of run, indoor_run, walk, hike, cycle, indoor_cycle, pool_swim, open_water_swim, indoor_row, hiit, elliptical; labels under 40 characters, zones 1 to 5, positive goals) and writes it to plans/. Set scheduled_for to the day and time the athlete will do it: the app schedules it on the Watch for that time (one tap in the Import tab, or automatically when the athlete switched that on). Ask the athlete before you write one.
Inputs: plan (required).
rate_workoutAIdempotent
Stores the effort the athlete told you (1 to 10) and an optional feel note in the session file, marked effort_source ai. Call it only after the athlete told you the number; Apple's own rating wins unless the athlete asks to change it (then pass override true).
Inputs: id (required), effort (required), feel, override.
training_summaryARead-onlyIdempotent
Per ISO week: sessions, time, distance, average heart rate, easy-zone share, mean effort (any source) and the cardiac cost trend (heart beats per 100 m at the best freestyle 100 pace, lower is better), plus volume by sport.
Inputs: weeks.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools occupy clearly distinct niches: get_workout (single session detail) vs list_workouts (compact rows) vs rate_workout (write effort) are separated by descriptions, and get_day/get_days/get_vitals differ in granularity. A few boundaries are soft — get_vitals overlaps with get_days for longitudinal trends, and list_ecgs overlaps with get_day's heart group — but an agent can reasonably choose.
Nearly everything follows a clean verb_noun snake_case pattern (get_day, list_plans, push_plan, rate_workout). The single outlier is training_summary, which is a noun phrase with no verb, a minor deviation in an otherwise predictable scheme.
Thirteen tools for a health-data server covering workouts, days, ECGs, plans, profile, vitals and summaries is well-scoped. Each tool maps to a distinct read or write need with no filler entries.
Read coverage is broad (days, workouts, ECGs, plans, profile, vitals, catalog) and writes exist for plans and effort ratings. However, list_ecgs advertises a voltage file but no tool retrieves ECG waveform data, and there is no way to delete or cancel a plan (only push_plan and get_plan_status), leaving dead ends in the lifecycle.
Maintenance
Related MCP Connectors
Apple Health training load, recovery, HRV and workout detail for Claude, ChatGPT and any MCP client.
Hosted Apple Health MCP: workouts, sleep and HRV in ChatGPT, Claude, Gemini, Grok. Free, no export.
Your Apple Health data, food diary and lifts, for ChatGPT, Claude and Gemini. Approved on iPhone.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Related MCP Servers
- AlicenseAqualityBmaintenanceLocal-first MCP server that reads Apple Health export files (export.xml/zip) and exposes activity, sleep, HRV, and workout data to AI agents, keeping all data on your machine.18260 npm3MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query personal health data collected by any wearable or phone fitness app through Android Health Connect or Apple Health, exposing read-only tools for metrics like heart rate, sleep stages, VO2 max, and body composition. It can run locally over USB with nothing stored, or be self-hosted on Cloudflare Workers with D1 to retain history beyond Health Connect's 30-day limit.20 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read your own Apple Health data through a self-hosted SQLite mirror, allowing them to query health metrics, workouts, meals, and strength logs without sending data to the cloud.105 PyPI4MIT
- AlicenseBqualityBmaintenanceLets Claude Code, Codex, and other AI assistants query locally collected Apple Health data, build weekly reports, check sync status, and log workouts or meals by hand.11MIT