Apple Health

Setup

On first use, read setup.md for integration guidelines.

When to Use

User wants agents to read Apple Health data for trends, summaries, or SQL analysis. Agent handles export validation, MCP server wiring, and safe query/report flows without exposing private health records.

Architecture

Memory lives in ~/apple-health/. See memory-template.md for setup.

~/apple-health/
|-- memory.md              # Status, client integration state, latest export path
|-- integrations.md        # Connected MCP clients and validation notes
|-- query-log.md           # Reusable SQL/report prompts and known-good outputs
`-- archive/               # Retired paths and old troubleshooting notes

Quick Reference

Use these files on demand instead of overloading the main instructions.

Core Rules

1. Confirm Integration Mode Before Doing Anything

Start by clarifying one of these modes:

• csv-export using Apple Health CSV exports and MCP
• not-now if user is only planning and does not want setup yet

Never imply direct HealthKit API access from terminal agents. This skill works from exported data.

2. Validate Local Export Before MCP Wiring

Require a real export folder before configuration:

• Must exist locally and be readable
• Must include files matching HKQuantityTypeIdentifier*.csv, HKCategoryTypeIdentifier*.csv, or HKWorkoutActivityType*.csv
• Must not be an empty unzip folder

If validation fails, stop and fix data path first.

3. Run Runtime Preflight Before MCP Configuration

Before wiring MCP, verify runtime:

• node -v should be an LTS line (18, 20, or 22)
• If npx @neiltron/apple-health-mcp fails with missing duckdb.node, switch to LTS Node and retry
• Confirm HEALTH_DATA_DIR is available as an absolute path

Do not continue while runtime is incompatible.

4. Configure MCP With Explicit Path and Command

Use the MCP server command from mcp-config.md:

• Command: npx
• Args: [@neiltron/apple-health-mcp]
• Env: HEALTH_DATA_DIR=/absolute/path/to/export

Never continue with placeholders or relative paths that are not verified.

5. Schema First, Then Queries

First run schema discovery (health_schema) and map available tables. Only then run health_query or health_report.

If table names differ from expectation, adapt SQL to discovered schema instead of forcing guessed names.

6. Use Date-Bounded Queries By Default

Every analytical query should include time bounds and clear units. Prefer rolling windows (last 7d, 30d, 90d) and compare at most two windows at once.

Avoid unbounded full-history scans unless user explicitly asks.