Skip to main content
Glama

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/tide for now; everything inside uses the new names. Files and settings written before the rename keep working: the tide.* schema ids, TIDE_DIR, ~/.config/tide/config.toml and the tide:// resource URIs are accepted as aliases forever. See docs/schema.md and docs/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

  1. Install the app: Health Access MCP on the App Store, free. Or build it from this repository with Xcode.

  2. 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.

  3. Allow Health access (read only, you choose the types) and notifications (one kind only: "Your AI wrote S27", when a plan arrives).

  4. 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

  1. You end a workout on the Watch.

  2. Next time the phone is unlocked, the app writes workouts/2026-05-14_0712_PoolSwim_7A1C3E90.json into 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.

  3. The folder syncs to your computer.

  4. Your AI reads it. No app on that side.

Sometimes, one tap, you

  1. 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.

  2. 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

  1. Reads sessions, vitals and trends through the MCP, or reads the JSON directly. The folder is the API.

  2. Writes a workout plan into plans/ with the day and time you said. It shows up in the app's Import tab.

  3. 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-mcp

That 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

list_workouts

Compact rows, newest first. One line per session, written for an LLM.

get_workout

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.

get_vitals

Resting heart rate, HRV, sleep, weight, steps, VO2max by day.

training_summary

Per week: volume, sessions, easy-zone share, mean effort, and the cardiac cost trend (beats per 100 m).

rate_workout

Stores the effort you told the AI. The AI must ask you, never guess.

push_plan

Validates a session (labels under 40 characters, zones 1 to 5) and writes it to plans/. Then the app, then your Watch.

get_plan_status

Whether the app has put a plan on the Watch yet: pending, scheduled, failed or cancelled.

list_plans

Every plan in plans/ with its state, newest first.

get_day, get_days

Everything Health holds for a day or a range, in groups: activity, heart, sleep, body, mind and more.

get_catalog

Every Health type, whether it has data and where it was exported.

get_profile

Age, sex, height and the other characteristics from profile.json.

list_ecgs

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 results

Nothing 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 scheme HealthAccess, product Health Access, bundle id com.healthaccessmcp.app. Project generated with XcodeGen from app/project.yml (never hand-edit the .xcodeproj). Details in app/README.md.

  • core/ Rust crate healthaccess-core (lib healthaccess_core): data contract models, folder store, zone math, derived training views, the Apple .workout codec.

  • mcp/ Rust crate healthaccess-mcp: the MCP server over stdio (binary healthaccess-mcp).

  • cli/ Rust crate healthaccess-cli: the healthaccess command-line tool.

  • examples/ a synthetic Health Access folder (generate.py rewrites 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, then claude 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.sh stages it with /ref/ and /examples/ into dist/site, scripts/deploy-site.sh deploys 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)

  1. Xcode installed, signed in with your Apple ID (Xcode, Settings, Accounts). A "Personal Team" appears.

  2. iPhone: Settings, Privacy & Security, Developer Mode on (reboot).

  3. cd app && xcodegen generate && open HealthAccess.xcodeproj

  4. In Xcode: Signing & Capabilities, Team = your Personal Team. Change the bundle id if it collides.

  5. Plug in the phone, select it, run. First run: trust the developer certificate on the phone (Settings, General, VPN & Device Management).

  6. 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>" doctor

Then 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 tools
get_catalogA
Read-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_dayA
Read-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_daysA
Read-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_statusC
Read-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_profileA
Read-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_vitalsA
Read-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_workoutA
Read-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_ecgsA
Read-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_plansA
Read-onlyIdempotent

Every plan in plans/ with its state, planned distance and time, newest first.

Inputs: no named parameters.

list_workoutsA
Read-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_workoutA
Idempotent

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_summaryA
Read-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

    A3.5/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Local-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.
      18
      260 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      4
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Lets 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.
      11
      MIT