Check the app
- Settings → Trust → Sync log lists every time the app woke and what it wrote. If a session is missing, this is where you see whether the app ran and what it found. Small buttons at the bottom write the last days again.
- Settings → Trust → What left this phone lists every event the app sent in this session, with the host. With usage statistics off it says nothing left.
- Settings → About shows the app version and the build number in brackets.
Check the computer
npx -y -p healthaccess-mcp healthaccess doctor # checks the folder: directories, index, every file, schema versions npx -y healthaccess-mcp --check # prints the folder the server uses and whether usage statistics are on npx -y healthaccess-mcp --version # prints the server version
Add --dir "<path to the folder>" to any of them to point them at a folder. If you installed with cargo, leave out the npx part: healthaccess doctor, healthaccess-mcp --check, healthaccess-mcp --version. doctor ends with healthy when everything in the folder reads correctly, and with PROBLEMS FOUND and the reasons when it does not.
Common problems
The app says "Not connected yet"
Your AI client has not started the MCP server yet. Clients start it when a new chat or session begins, so start one. The server then writes a small file into mcp/clients/ in your folder. Once your folder provider has synced that file to the phone, the app shows the connection. It checks again each time it comes to the front, so switch to it after a minute. The app also shows "Not connected yet" again when the AI has not used the server for 7 days.
No new sessions in the folder
Open the app once after the workout. The iPhone must be unlocked, because Apple Health data cannot be read while the phone is locked; the app writes the files at the next unlock. Then the folder provider has to sync the files to your computer. On a Mac, iCloud Drive shows a cloud icon on files that are not downloaded yet. If the sync log shows a run with nothing new, check that Health Access may read your workouts in Health → Sharing → Apps → Health Access.
Plans do not reach the Watch
Your AI writes the plan into the folder. It reaches the Watch only after you open the app, tap Put on Watch on that plan and confirm. The plan file has to have synced to the phone first. Putting a workout on the Watch uses Apple's WorkoutKit and needs an Apple Watch paired with this iPhone. Settings → Watch sets what Put on Watch does: schedule the session, or open Apple's preview sheet. Apple's preview sheet does not report back, so the app marks those plans as unconfirmed.
The MCP server cannot find the folder
Without --dir, the server looks for the folder in iCloud Drive, then in the other file providers, then in ~/Documents. If it finds none, or picks the wrong one, tell it where the folder is with --dir "<path to the folder>", in the arguments your AI client uses to start the server. On a Mac, a folder in iCloud Drive is at ~/Library/Mobile Documents/com~apple~CloudDocs/<folder name>. Dropbox, Google Drive and OneDrive folders usually live under ~/Library/CloudStorage/. For example:
{
"mcpServers": {
"healthaccess": {
"command": "npx",
"args": ["-y", "healthaccess-mcp", "--dir", "/Users/<you>/Library/Mobile Documents/com~apple~CloudDocs/Health Access"]
}
}
}
Start a new session in the client afterwards. npx -y healthaccess-mcp --check prints the folder the server uses and any other Health Access folders it found. Add --dir "<path>" to it to test a path. The pages under Connect an AI show where each client keeps these settings.
Write to us
Write to support@healthaccessmcp.com and include:
- your iOS version;
- the app version and build, from Settings → About;
- which AI client you use, with its version if you know it;
- what you expected, and what happened instead;
- the output of
npx -y -p healthaccess-mcp healthaccess doctor.
Never send us health data files from your folder. We do not need them to help you. The doctor output holds no health values, but it shows your folder's path and your computer's name and, where something failed, file names and Health data types. Remove anything you would rather not share. What we do with your mail is in the privacy policy.
Purchases
The support card and the coffee are sold by Apple. Refunds go through Apple at reportaproblem.apple.com. We cannot see who bought and cannot refund a purchase ourselves. On a new phone or after a reinstall, Settings → About → Restore purchases brings back a removed support card.
Source code
The source code repository will be public soon. Until then, email is the way to reach us.