Apple Health
by @ivangdavila
Connect agents to Apple Health exports with MCP setup, schema validation, and privacy-safe analysis.
clawhub install apple-healthπ About This Skill
name: Apple Health slug: apple-health version: 1.0.0 homepage: https://clawic.com/skills/apple-health description: Connect agents to Apple Health exports with MCP setup, schema validation, and privacy-safe analysis. changelog: Initial release with Apple Health MCP integration workflow and guarded query patterns. metadata: {"clawdbot":{"emoji":"β€οΈ","requires":{"bins":["node","npx"],"env":["HEALTH_DATA_DIR"]},"install":[{"id":"npm","kind":"npm","package":"@neiltron/apple-health-mcp","bins":["apple-health-mcp"],"label":"Install Apple Health MCP Server (npm)"}],"os":["darwin","linux","win32"]}}
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.
| Topic | File |
|-------|------|
| Setup process | setup.md |
| Memory template | memory-template.md |
| MCP client wiring | mcp-config.md |
| Query recipes | query-recipes.md |
| Fallback CLI paths | fallback-cli.md |
Core Rules
1. Confirm Integration Mode Before Doing Anything
Start by clarifying one of these modes: using Apple Health CSV exports and MCP if user is only planning and does not want setup yetNever 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:, HKCategoryTypeIdentifier*.csv, or HKWorkoutActivityType*.csvIf validation fails, stop and fix data path first.
3. Run Runtime Preflight Before MCP Configuration
Before wiring MCP, verify runtime: should be an LTS line (18, 20, or 22) fails with missing duckdb.node, switch to LTS Node and retry is available as an absolute pathDo 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/exportNever continue with placeholders or relative paths that are not verified.
5. Schema First, Then Queries
First run schema discovery () 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.
7. Track Data Freshness and Refresh Points
Log last export timestamp in memory and warn when data is stale.
If user needs current-day insights, request a new iPhone export before claiming "latest" trends.Common Traps
Assuming live HealthKit access from CLI agents -> setup fails because only exported data is available
Using wrong export path in MCP env -> server starts but returns no data
Running SQL before schema discovery -> queries fail on wrong table names
Unbounded queries on large exports -> slow analysis and noisy output
Reporting "today" metrics from stale export -> inaccurate recommendations
Running MCP package on non-LTS Node -> DuckDB native module errors can break startup External Endpoints
| Endpoint | Data Sent | Purpose |
|----------|-----------|---------|
| https://registry.npmjs.org | Package install metadata only | Download MCP server package |
| https://raw.githubusercontent.com | Public markdown only | Read validated fallback skill docs |
| https://apps.apple.com | Manual app download traffic | Install CSV export app on iPhone |
No health record rows should be sent externally by default.
Security & Privacy
Data that leaves your machine:
Package install requests to npm
Optional app download traffic from App Store Data that stays local:
Apple Health CSV exports
MCP query outputs and summaries
Skill memory in ~/apple-health/This skill does NOT:
Access iCloud Health data directly
Bypass Apple permission prompts
Upload health CSVs unless the user asks for that explicitly Trust
By using this skill, you rely on third-party tooling (
and the chosen iPhone export app).
Only install and run if you trust those tools.Related Skills
Install with clawhub install if user confirms:
health - General health guidance boundaries and framing
ios - iOS-specific setup and platform troubleshooting
sleep - Sleep trend interpretation workflows
api - Reliable API and integration debugging habits
swift - HealthKit-side implementation context when app code is involvedFeedback
If useful: clawhub star apple-health
Stay updated: clawhub sync`
β‘ 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.
βοΈ Configuration
On first use, read setup.md for integration guidelines.