healthfolder

Read a Health Access folder of Apple Watch workouts and vitals, and write training plans back into it — as plain files. The folder an app writes from Apple Health (workouts, day files, an index, a profile) is the whole API: this package is a local stdio MCP server plus a CLI over that folder. No account, no network, nothing leaves the machine.

How the folder is found

First hit wins:

1. --dir <folder> on the command line
2. the HEALTHACCESS_DIR environment variable (alias TIDE_DIR)
3. dir = "..." in ~/.config/healthaccess/config.toml (the path can be overridden with HEALTHACCESS_CONFIG; zone bounds can also be set there as zones = [133, 146, 158, 169])
4. discovery: iCloud Drive, then ~/Library/CloudStorage/*, ~/Dropbox, ~/Google Drive, ~/OneDrive*, ~/Box, then ~/Documents. A Health Access folder holds an index.json of schema healthaccess.index.v1 and a workouts/ directory. If discovery finds several, the server refuses to guess and lists them.

Run healthfolder --check to print the resolved folder, where it came from, and the zone bounds in effect.

CLI

npx -y @reneturcios/healthfolder --check
npx -y @reneturcios/healthfolder list --sport swim --limit 5
npx -y @reneturcios/healthfolder show 7A1C3E90
npx -y @reneturcios/healthfolder vitals --days 14
npx -y @reneturcios/healthfolder summary --weeks 4
npx -y @reneturcios/healthfolder rate 7A1C3E90 7 "legs heavy, breathing fine"
npx -y @reneturcios/healthfolder plan push ./s30.json
npx -y @reneturcios/healthfolder plan status 2026-10-24T20:22:05Z-s30
npx -y @reneturcios/healthfolder plan list
npx -y @reneturcios/healthfolder day 2026-05-14
npx -y @reneturcios/healthfolder days --from 2026-05-01 --to 2026-05-14 --groups heart,sleep
npx -y @reneturcios/healthfolder catalog
npx -y @reneturcios/healthfolder profile
npx -y @reneturcios/healthfolder ecgs

Every command prints pretty JSON. Exit codes: 0 success, 1 domain or IO error, 2 usage error. --dir works on every subcommand.

MCP server

npx -y @reneturcios/healthfolder mcp

MCP client config:

{
  "mcpServers": {
    "healthfolder": {
      "command": "npx",
      "args": ["-y", "@reneturcios/healthfolder", "mcp"]
    }
  }
}

Add "--dir", "<absolute path>" to args to skip the folder search.

Tools (13)

All results are pretty-printed JSON text with floats rounded to one decimal. Malformed arguments are JSON-RPC InvalidParams errors; domain problems (unknown id, failed validation, a refusal) come back as isError results with the reason in plain words.

Two safety rules are built in:

• rate_workout only ever stores a number the athlete said. A workout that already carries Apple's own rating (effort_source: "apple") is refused unless the call passes override: true — the refusal names the file, the existing rating, an

... View full README on GitHub