# Reported issues for Apple Health

Pod holds 8 of 8 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Apple Health](/mcp/apple-health).

## Most discussed

### Catalogue is never rescanned and loadedTables always reports 0, so a working server looks empty

Two related issues in `FileCatalog` / `HealthSchemaTool` make a working server look empty. Both are easy to hit and produce silent wrong answers rather than errors.

### 1. The file catalogue is scanned once and never refreshed

`main()` calls `catalog.initialize()` -> `scanDirectory()` exactly once at start-up. Nothing ever rescans.

If the MCP client starts the server before `HEALTH_DATA_DIR` is populated — which is the normal case when you are still converting/exporting your data, or when the

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/12) · 2026-07-31 · closed · external user · 1 comment

### Workout data can never be loaded: catalog regex requires a literal 'TypeIdentifier'

## Summary

The file catalog only matches filenames containing a literal `TypeIdentifier`, so workout data can never be catalogued. As a result `health_report`'s workout section always fails, and workouts are unreachable from `health_query`.

## Cause

`dist/server.js` (`src/db/catalog.ts`):

```js
const match = file.match(/^(HK\w+TypeIdentifier\w+).*\.csv$/);
```

Workout files are named `HKWorkoutActivityType.csv` — no `TypeIdentifier` — so the regex never matches and no `hkworkoutactivitytype

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/11) · 2026-07-31 · closed · external user · 0 comments

### health_report returns empty sections on a cold server: HealthReportTool never loads its tables

## Summary

`HealthReportTool` is constructed without a `TableLoader`, so `health_report` queries tables that were never loaded. On a freshly started server every section fails and the report comes back empty.

## Reproduce

Start the server against a data directory and call `health_report` as the very first tool call:

```json
{ "name": "health_report", "arguments": { "report_type": "monthly" } }
```

Result:

```json
{ "title": "Monthly Health Report (...)", "sections": [], "summary": "" }
```

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/10) · 2026-07-31 · closed · external user · 0 comments

### Sleep analysis always reports zero: stage labels are cast away and the report filters on the wrong column

### Summary

Sleep data is unusable in the current version. Two separate problems combine:

1. The loader casts `value` to `DOUBLE`, which destroys the sleep stage labels (`asleepCore`, `asleepDeep`, `asleepREM`, `inBed`) — they all become `NULL`. The information is not exposed anywhere else, so an LLM writing its own SQL through `health_query` cannot recover it either.
2. `generateSleepSection()` filters on `WHERE type LIKE '%Asleep%'`, but `type` is `HKCategoryTypeIdentifierSleepAnalysis`

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/9) · 2026-07-31 · closed · external user · 0 comments

### health_schema silently truncates every table to 100 rows, causing wrong results in all later queries

### Summary

`health_schema` loads each table with `LIMIT 100` and then marks it as fully loaded in the catalog. Because `TableLoader.ensureTableLoaded()` returns early for tables the catalog reports as loaded, the full data is **never** loaded. Every subsequent `health_query` and `health_report` call silently runs against only the first 100 rows.

This is a silent correctness bug rather than a crash: the server returns confident, well-formed answers computed from a small fraction of the dat

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/8) · 2026-07-31 · closed · external user · 0 comments

### HKCategoryType and Workout tables fail — hardcoded `unit` column reference

## Bug Summary

All 8 `HKCategoryType` tables and all 13 workout-type tables fail to load with **"Referenced column 'unit' not found"** because `cleanAndOptimizeTable()` and `loadTableSample()` hardcode a `unit` column reference that only exists in quantity-type CSVs.

## Environment

- Apple Health data exported via **Simple Health Export** iOS app (96 CSV files)
- apple-health-mcp running on macOS with DuckDB

## Root Cause

The CSV export from Apple Health has **three distinct table schemas**

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/6) · 2026-02-09 · closed · external user · 1 comment

### Node version compatibility issues

Leaving a breadcrumb here if anyone runs across this. Not sure if the apple health mcp server can make this experience any better (Claude Desktop certainly doensn't make it easy), but if you have `nvm` installed it seems to conflict with how Claude Desktop loads the system version of `node` on macOS. 

This can be overridden in the `claude_desktop_config.json` via these steps
https://github.com/anthropics/claude-code/issues/539#issuecomment-3166366708

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/3) · 2025-08-08 · closed · external user · 2 comments

### Add unit hints: The SQL queries it generates sometimes assume units - e.g. a short bike ride I had (0.87km) was reported as 0.87 metres!

Wonder if there is a way to prompt/hint/transform the fields so it sees distance_in_km or something to help it correctly work it out?

[Read the thread](https://github.com/neiltron/apple-health-mcp/issues/1) · 2025-07-29 · closed · external user · 1 comment

## Most recent

The remaining reports are on [the project's issue tracker](https://github.com/neiltron/apple-health-mcp/issues).